# Dashboard Specification: [Dashboard name]

> Specification of one dashboard or BI report: its audience and the
> decisions it supports, the questions it answers, the KPI list (each
> linked to a Metric Definition), the layout wireframe, filters and
> drill paths, row-level security, refresh and data latency,
> accessibility against W3C WCAG 2.2 (Recommendation, 12 December 2024
> edition), the performance budget, testing, ownership, certification
> and the sunset date. Tool-neutral: it works for any BI or notebook
> tool. Replace every `[bracketed]` value and every row marked
> *Example*.

<!--
Guidance: How to use this template
- One specification per dashboard or report. Write it before building,
  agree it with the audience, then keep it current as the dashboard
  changes. A dashboard without a specification cannot be certified.
- Fill sections 1 (audience and decisions) and 2 (questions) before any
  layout work. If you cannot name the decision, you probably need an ad
  hoc analysis, not a dashboard.
- Boundaries with neighbouring documents:
  - Metric Definition (`data/metric-definition`) owns the meaning of
    each KPI. This document only lists KPIs and links to them.
  - Semantic Model Specification (`data/semantic-model-specification`)
    owns joins, dimensions and metric logic. The dashboard queries the
    model; it does not redefine metrics.
  - Analytics and BI Solution Design
    (`architecture/analytics-bi-solution-design`) sets platform-wide
    report standards, distribution and capacity.
  - Accessibility Audit (`quality/accessibility-audit`) is the formal
    conformance evaluation; section 10 here sets the build requirements.
- The worked example is the "Executive Sales Dashboard" of Corvid
  Commerce, a fictional SaaS retailer.
-->

## Document control

<!-- Guidance: Identify the dashboard, the tool and workspace it lives in, the business owner who decides what it shows, and its sunset date. Every dashboard gets a sunset date at creation. -->

| Field | Value |
|---|---|
| Document ID | [DSH-001] *(Example)* |
| Dashboard name | [Executive Sales Dashboard] *(Example)* |
| Tool and workspace | [BI tool, workspace or folder] |
| URL | [link to the published dashboard] |
| Semantic model | [SEM-ORD-001] *(Example)* |
| Version | [1.0] |
| Status | [Draft / In build / In review / Certified / Deprecated / Retired] |
| Owner | [@business-owner] |
| Developer | [@bi-developer] |
| Approvers/reviewers | [@head-of-sales], [@data-governance-lead], [@accessibility-reviewer] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Certification review | YYYY-MM-DD |
| Sunset date | YYYY-MM-DD (review or retire on this date) |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Business owner | [@name] | [Approved / Changes requested] | YYYY-MM-DD |
| Data governance lead | [@name] | [Certified / Not certified] | YYYY-MM-DD |
| Accessibility reviewer | [@name] | [Passed / Passed with exceptions / Failed] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@author] | First draft agreed with audience |
| 1.0 | YYYY-MM-DD | [@author] | Certified and published |

## Contents

- [1. Audience and decisions](#1-audience-and-decisions)
- [2. Questions answered](#2-questions-answered)
- [3. KPIs and metrics](#3-kpis-and-metrics)
- [4. Data sources and lineage](#4-data-sources-and-lineage)
- [5. Layout and wireframe](#5-layout-and-wireframe)
- [6. Visual and content rules](#6-visual-and-content-rules)
- [7. Filters, parameters and drill paths](#7-filters-parameters-and-drill-paths)
- [8. Row-level security and sharing](#8-row-level-security-and-sharing)
- [9. Refresh, latency and data status](#9-refresh-latency-and-data-status)
- [10. Accessibility](#10-accessibility)
- [11. Performance budget](#11-performance-budget)
- [12. Testing and acceptance](#12-testing-and-acceptance)
- [13. Ownership, certification and sunset](#13-ownership-certification-and-sunset)
- [14. Glossary and references](#14-glossary-and-references)

## 1. Audience and decisions

<!-- Guidance: Name the people who use the dashboard, how often, on which device, and the decisions they take with it. Questions: what will they do differently because of a number on this page? Pitfall: "everyone" as the audience, which produces a page that serves nobody well. -->

| Audience ID | Audience | Use frequency | Device and context | Decision supported *(Example)* |
|---|---|---|---|---|
| AUD-01 *(Example)* | Executive team | Weekly business review, Monday | Large screen in meeting room, laptop | Shift budget between regions and channels |
| AUD-02 *(Example)* | Regional sales managers | Daily | Laptop, sometimes phone | Prioritise promotions for underperforming categories |
| AUD-03 *(Example)* | Finance business partners | Month end | Laptop | Explain revenue variance to plan |
| [AUD-NN] | [audience] | [frequency] | [device] | [decision] |

Not intended for *(Example)*: operational monitoring of the checkout
service (use the observability dashboards), or customer-level
investigation (use the CRM).

## 2. Questions answered

<!-- Guidance: List the questions in the order the audience asks them. Each question maps to one visual or one page. Pitfall: adding visuals that answer no listed question because "the data was there". -->

| Q ID | Question | Audience | Answered by visual |
|---|---|---|---|
| Q-01 *(Example)* | How is net revenue tracking against plan this fiscal month? | AUD-01, AUD-03 | V-01, V-02 |
| Q-02 *(Example)* | Which regions and channels drive the variance? | AUD-01, AUD-02 | V-03 |
| Q-03 *(Example)* | Is average order value moving, and in which customer segment? | AUD-01 | V-04 |
| Q-04 *(Example)* | Which categories are below last year in my region? | AUD-02 | V-05 |
| Q-05 *(Example)* | Are refunds within 30 days rising? | AUD-01, AUD-03 | V-06 |
| [Q-NN] | [question] | [AUD-NN] | [V-NN] |

## 3. KPIs and metrics

<!-- Guidance: List each KPI with the metric ID from the semantic model and a link to its Metric Definition. Questions: is each metric certified, and does the dashboard apply any extra filter to it? Pitfall: a calculated field in the dashboard that silently redefines a certified metric. -->

| KPI ID | Label shown | Metric ID | Metric definition | Certified | Comparison | Target source *(Example)* |
|---|---|---|---|---|---|---|
| KPI-01 *(Example)* | Net revenue | MET-REV-001 | Metric Definition MET-REV-001 | Yes | Plan, same period last year | Finance plan, monthly |
| KPI-02 *(Example)* | Orders | MET-ORD-001 | Metric Definition MET-ORD-001 | Yes | Same period last year | None |
| KPI-03 *(Example)* | Average order value | MET-REV-003 | Metric Definition MET-REV-003 | Yes | Same period last year | None |
| KPI-04 *(Example)* | Net revenue growth vs last year | MET-REV-004 | Metric Definition MET-REV-004 | Yes | Plan growth | Finance plan |
| KPI-05 *(Example)* | Refund within 30 days | MET-ORD-002 | Metric Definition MET-ORD-002 | No (labelled "Preview") | Previous 3 months | None |
| [KPI-NN] | [label] | [MET-ID] | [link] | [Yes / No] | [comparison] | [source] |

Rules:

- **DSH-R01** Every KPI comes from the semantic model. Dashboard-level
  calculations are limited to formatting and to comparisons the model
  cannot provide, and each one is listed here.
- **DSH-R02** An uncertified metric is visibly labelled (for example
  "Preview") and placed below certified KPIs.
- **DSH-R03** Each KPI tile links to its Metric Definition
  (`data/metric-definition`) from an information icon or tooltip.

## 4. Data sources and lineage

<!-- Guidance: Show what the dashboard reads and what it depends on, so impact analysis works in both directions. Pitfall: a dashboard that reads a staging table directly and breaks when it changes. -->

```mermaid
flowchart LR
  SRC[Sources: shop_db, payments_api] --> MART[Marts: fct_orders, fct_order_lines, fct_refunds, dim_customers, dim_calendar]
  MART --> SEM[Semantic model SEM-ORD-001]
  PLAN[Finance plan table] --> SEM
  SEM --> DSH[DSH-001 Executive Sales Dashboard]
  DSH --> SUB[Monday e-mail snapshot]
```

| Dependency | Type | Owner | Declared as exposure | Notes *(Example)* |
|---|---|---|---|---|
| SEM-ORD-001 | Semantic model | [@analytics-engineer] | Yes | Only path to order and revenue data |
| `finance.plan_monthly` | Table | [@finance-analytics] | Yes | Loaded on business day 2 of each month |
| [dependency] | [type] | [@owner] | [Yes / No] | [notes] |

Register the dashboard as an exposure in the transformation project
(rule DBT-055 in dbt Project Standard, `data/dbt-project-standard`) so
model changes show it as affected.

## 5. Layout and wireframe

<!-- Guidance: Sketch the page before building. Put the most important answer top left, summary before detail, and keep to the visual budget agreed in the BI standards. Pitfall: a wall of equal-sized charts with no reading order. -->

Page 1, "Overview" *(Example)*:

```text
+------------------------------------------------------------------+
| Title, data as of [time], filters applied: [Region] [Channel]    |
+---------------+---------------+---------------+------------------+
| V-01 KPI tile | V-01 KPI tile | V-01 KPI tile | V-01 KPI tile    |
| Net revenue   | Orders        | Avg order val | Growth vs LY     |
+---------------+---------------+---------------+------------------+
| V-02 Net revenue vs plan, by week (line)  | V-03 Variance by     |
|                                           | region and channel   |
|                                           | (bar, sorted)        |
+-------------------------------------------+----------------------+
| V-04 AOV by segment (line, small multiples) | V-06 Refund rate   |
|                                             | (line, Preview)    |
+---------------------------------------------+--------------------+
| Footnotes: definitions, exclusions, contact                       |
+------------------------------------------------------------------+
```

Page 2, "Categories" *(Example)*: V-05 category table with last year
comparison, conditional icons and drill-through to a category detail
page.

| Visual ID | Title | Chart type | Metrics | Dimensions | Answers |
|---|---|---|---|---|---|
| V-01 *(Example)* | Headline KPIs | KPI tiles with comparison | KPI-01 to KPI-04 | Fiscal month to date | Q-01 |
| V-02 *(Example)* | Net revenue vs plan | Line, actual and plan | KPI-01 | Week | Q-01 |
| V-03 *(Example)* | Variance by region and channel | Horizontal bar, sorted by variance | KPI-01 | Region, channel | Q-02 |
| V-04 *(Example)* | Average order value by segment | Line, small multiples | KPI-03 | Week, segment | Q-03 |
| V-05 *(Example)* | Categories vs last year | Table with icons | KPI-01, KPI-02 | Category, region | Q-04 |
| V-06 *(Example)* | Refund within 30 days | Line | KPI-05 | Month | Q-05 |
| [V-NN] | [title] | [chart type] | [KPI-NN] | [dimensions] | [Q-NN] |

## 6. Visual and content rules

<!-- Guidance: Record the choices that keep numbers readable and honest. Pitfall: truncated axes on bar charts that exaggerate small differences. -->

- **DSH-R10** Bar charts start at zero; line charts may use a fitted axis
  when the axis is labelled.
- **DSH-R11** Show units and currency codes on every number and axis
  (*Example*: "EUR, thousands").
- **DSH-R12** Use the same colour for the same category on every page;
  reserve one highlight colour for "below plan".
- **DSH-R13** Sort categorical bars by value unless the categories have a
  natural order.
- **DSH-R14** Write titles as findings or questions (*Example*: "Net
  revenue vs plan, fiscal month to date"), and put definitions,
  exclusions and the contact in the footnote.
- **DSH-R15** No 3D charts, no dual axes with different units, no pie
  charts with more than [4] slices *(Example)*.
- **DSH-R16** Follow the platform report standards in Analytics and BI
  Solution Design (`architecture/analytics-bi-solution-design`, section
  "Report and dashboard standards").

## 7. Filters, parameters and drill paths

<!-- Guidance: List every filter, its default and its scope, and every drill path. Questions: does a filter apply to all pages, and is the active filter state visible? Pitfall: a default filter that hides part of the data while the title suggests a total. -->

| Filter ID | Filter | Type | Default | Scope | Visible in header *(Example)* |
|---|---|---|---|---|---|
| F-01 *(Example)* | Fiscal period | Single select | Current fiscal month | All pages | Yes |
| F-02 *(Example)* | Region | Multi select | All regions the user may see | All pages | Yes |
| F-03 *(Example)* | Sales channel | Multi select | All | All pages | Yes |
| F-04 *(Example)* | Customer segment | Multi select | All | Page 1, V-04 only | Yes |
| [F-NN] | [filter] | [type] | [default] | [scope] | [Yes / No] |

| Drill ID | From | To | Carries filters | Purpose *(Example)* |
|---|---|---|---|---|
| DR-01 *(Example)* | V-03 bar (region) | Region detail page | F-01, F-03, selected region | See weekly trend for one region |
| DR-02 *(Example)* | V-05 row (category) | Category detail page | F-01, F-02, selected category | See top products in a category |
| [DR-NN] | [from] | [to] | [filters] | [purpose] |

- **DSH-R20** The header always shows the active filters in text, not
  only in filter controls.
- **DSH-R21** Drill paths never lead to customer-level rows; the lowest
  grain is [product by day] *(Example)*.

## 8. Row-level security and sharing

<!-- Guidance: State who sees which rows, where the rule is enforced and how sharing works. Questions: do e-mail snapshots and exports respect the same rules? Pitfall: a scheduled export sent with the developer's permissions to a distribution list. -->

| Rule ID | Audience | Rows visible | Enforced in | Tested by *(Example)* |
|---|---|---|---|---|
| RLS-01 *(Example)* | Executive team, finance | All regions | SEM-ORD-001 access rule ACC-03 (finance and the executive team) | TC-06 |
| RLS-02 *(Example)* | Regional managers | Own region only | Row access policy, SEM-ORD-001 rule ACC-02 | TC-06 |
| [RLS-NN] | [audience] | [rows] | [layer] | [test] |

- **DSH-R30** Row-level rules are inherited from the semantic model or
  the data platform, never defined only inside the dashboard.
- **DSH-R31** Scheduled snapshots run as each recipient, or are limited
  to content every recipient may see.
- **DSH-R32** Data export is [disabled / limited to aggregated data]
  *(Example: limited to aggregated visuals, no underlying rows)*.
- **DSH-R33** Usage measurement for this dashboard uses aggregate view
  counts from the BI tool's own logs; no third-party tracking scripts,
  no individual-level profiling, and no data beyond what is needed to
  decide whether to keep the dashboard.

## 9. Refresh, latency and data status

<!-- Guidance: Say how fresh the data is, when it refreshes and how users know when it is late or wrong. Pitfall: a dashboard that shows yesterday's numbers as if they were today's because a load failed. -->

| Item | Specification *(Example)* |
|---|---|
| Data latency objective | Data complete to the end of the previous day by 07:00 UTC |
| Refresh method | Live query to the semantic model, cached for 60 minutes |
| Plan data | Monthly, by business day 2 |
| Data as-of indicator | Header shows "Data as of [timestamp], [time zone]" from the latest source freshness check |
| Late data behaviour | Banner "Data delayed, last complete day: [date]"; KPIs keep the last complete day |
| Known incident behaviour | Banner with link to the incident; severity per Incident Severity Matrix (`ops/incident-severity-matrix`) |
| Partial periods | Current week and month marked as incomplete |

Freshness and quality thresholds come from the source data contracts and
from Data Quality Standard (`data/data-quality-standard`).

## 10. Accessibility

<!-- Guidance: Set build requirements that meet WCAG 2.2 level AA for the dashboard page and its visuals. Questions: can a keyboard user reach every filter, can a screen reader user get the numbers, does meaning survive without colour? Pitfall: charts as images with no text alternative and red and green as the only signal. -->

Target conformance: WCAG 2.2 level [AA] for the dashboard page, within
the limits of the BI tool. Record tool limitations as exceptions with a
workaround.

| Req ID | Requirement | WCAG 2.2 success criterion | Check *(Example)* |
|---|---|---|---|
| A11Y-01 | Every chart has a short text alternative stating the main finding, plus access to the underlying aggregated table | 1.1.1 Non-text Content | Screen reader test |
| A11Y-02 | Headings, KPI labels and tables are exposed with correct structure | 1.3.1 Info and Relationships | Accessibility tree inspection |
| A11Y-03 | Colour is never the only way to show status or series; add labels, icons or patterns | 1.4.1 Use of Color | Greyscale review |
| A11Y-04 | Text and numbers meet the minimum contrast ratio (4.5:1 for normal text) | 1.4.3 Contrast (Minimum) | Contrast checker |
| A11Y-05 | Lines, bars, focus indicators and filter controls meet 3:1 against adjacent colours | 1.4.11 Non-text Contrast | Contrast checker |
| A11Y-06 | The page reflows without loss at 320 CSS pixels wide, or a mobile layout is provided. Charts and data tables may scroll in two dimensions under the 1.4.10 exception for content that needs a two-dimensional layout; the rest of the page (header, filters, KPI tiles, footnotes) must reflow | 1.4.10 Reflow | Browser zoom 400 percent |
| A11Y-07 | Tooltips can be dismissed without moving focus, can be hovered, and stay visible until hover or focus moves away or the user dismisses them | 1.4.13 Content on Hover or Focus | Manual test |
| A11Y-08 | Every filter, tab, visual and drill action works with a keyboard | 2.1.1 Keyboard | Keyboard-only walkthrough |
| A11Y-09 | Focus is visible and is not hidden by sticky headers or panels | 2.4.7 Focus Visible, 2.4.11 Focus Not Obscured (Minimum) | Keyboard walkthrough |
| A11Y-10 | Interactive targets are at least 24 by 24 CSS pixels or adequately spaced | 2.5.8 Target Size (Minimum) | Measurement |
| A11Y-11 | Auto-rotating pages or animations can be paused | 2.2.2 Pause, Stop, Hide | Manual test |
| A11Y-12 | Custom controls expose name, role and state to assistive technology | 4.1.2 Name, Role, Value | Accessibility tree inspection |

Use the Accessibility Checklist (`design/accessibility-checklist`) during
build and the Accessibility Audit (`quality/accessibility-audit`) for
the formal evaluation before certification.

## 11. Performance budget

<!-- Guidance: Set measurable limits so the dashboard stays usable as data grows. Questions: what is the slowest acceptable first view on a typical laptop and network, how many queries does one page fire? Pitfall: a page with twenty visuals that each run their own heavy query. -->

| Budget ID | Measure | Budget *(Example)* | Measured on |
|---|---|---|---|
| PB-01 | Time to first meaningful view (cached) | 3 seconds at the 90th percentile | Typical office laptop and network |
| PB-02 | Time to first meaningful view (uncached) | 10 seconds at the 90th percentile | Same |
| PB-03 | Filter change to updated visuals | 3 seconds at the 90th percentile | Same |
| PB-04 | Queries per page view | 12 or fewer | Query log |
| PB-05 | Visuals per page | 8 or fewer | Design review |
| PB-06 | Compute cost per month | Within [budget] tagged to this dashboard | FinOps Cost Review (`ops/finops-cost-review`) |

When a budget is breached for [2] consecutive weeks *(Example)*, open a
ticket: reduce visuals, pre-aggregate in a mart, or increase caching.
Plan load tests with Performance Test Plan
(`quality/performance-test-plan`) for dashboards with more than [200]
daily users *(Example)*.

## 12. Testing and acceptance

<!-- Guidance: List the tests that must pass before the dashboard is certified, including number reconciliation and security. Pitfall: user acceptance done by the developer alone. -->

| Test ID | Test | Expected result *(Example)* | Owner |
|---|---|---|---|
| TC-01 | Each KPI equals the semantic model saved query for the same filters | Exact match | [@bi-developer] |
| TC-02 | Net revenue for the last closed month reconciles with finance | Within 0.5 percent | [@finance-analytics] |
| TC-03 | Every filter and drill path works and carries filters as specified | All pass | [@bi-developer] |
| TC-04 | Late data banner appears when source freshness fails | Banner shown, KPIs hold last complete day | [@analytics-engineer] |
| TC-05 | Accessibility requirements A11Y-01 to A11Y-12 | Pass or recorded exception | [@accessibility-reviewer] |
| TC-06 | Regional manager test identity sees only its own region, and an executive test identity sees all regions, including in snapshots | Pass | [@security-reviewer] |
| TC-07 | Performance budgets PB-01 to PB-04 | Within budget | [@bi-developer] |
| TC-08 | User acceptance with two members of each audience | Questions Q-01 to Q-05 answered without help | [@business-owner] |

## 13. Ownership, certification and sunset

<!-- Guidance: Name the owners, the certification criteria and the date the dashboard must justify its existence again. Pitfall: hundreds of uncertified, unowned dashboards that compete with the certified one. -->

| Role | Responsibility | Person |
|---|---|---|
| Business owner | Decides content and audience, approves changes | [@business-owner] |
| BI developer | Builds and maintains the dashboard | [@bi-developer] |
| Data steward | Keeps definitions and footnotes accurate | [@data-steward] |
| Support contact | Answers user questions | [channel or queue] |

Certification requires: all KPIs certified or labelled as preview, tests
TC-01 to TC-08 passed, owner and support contact named, and the
dashboard registered as an exposure. Certification lasts [12 months]
*(Example)*.

Sunset and review:

1. At the sunset date, the owner reviews aggregate usage, open issues and
   whether the decisions in section 1 still exist.
2. The owner chooses: renew (new sunset date), redesign (new version of
   this specification) or retire.
3. To retire, announce [30 days] *(Example)* ahead, archive this
   specification, remove the exposure and delete the dashboard.
4. A dashboard with no named owner for [60 days] *(Example)* loses its
   certified status automatically.

## 14. Glossary and references

<!-- Guidance: Define terms the audience may not know and list the standards and documents this specification relies on. -->

| Term | Meaning |
|---|---|
| KPI | A metric chosen to track progress toward a goal, shown prominently |
| Certified | Approved by the business owner and data governance as correct and supported |
| Drill path | Navigation from a summary visual to more detailed data with filters carried |
| Row-level security | Rules that limit which rows a user can see |
| Data latency | Time between an event and its appearance in the dashboard |
| Exposure | A declared downstream consumer registered in the transformation project |
| Sunset date | Date by which the dashboard must be renewed or retired |

References:

- W3C, Web Content Accessibility Guidelines (WCAG) 2.2, W3C
  Recommendation, edition of 12 December 2024:
  https://www.w3.org/TR/WCAG22/
- Related templates: Metric Definition (`data/metric-definition`),
  Semantic Model Specification (`data/semantic-model-specification`),
  Analytics and BI Solution Design
  (`architecture/analytics-bi-solution-design`), Data Dictionary
  (`architecture/data-dictionary`), Data Platform Architecture
  (`architecture/data-platform-architecture`), Accessibility Audit
  (`quality/accessibility-audit`), Analytics Tracking Plan
  (`data/analytics-tracking-plan`) for product event data that feeds
  metrics.

## Standard and licence note

Based on the success criteria of W3C Web Content Accessibility
Guidelines (WCAG) 2.2, cited by number and short name only under the W3C
document licence; no WCAG text is reproduced. The rest of the structure
is original, aligned with common business intelligence practice, and
the Corvid Commerce example is fictional. This template is original text
written for this collection. Check the current official WCAG version
and your BI tool's documentation before use. Template licence: MIT.