aiRA data visualisation companion v0.2

The charts, tables and dashboards aiRA draws, specified the way the aiRA Design System specifies everything else. This release covers the core chart set, the specialist charts, the analytics settings and table patterns Power BI users expect, and the three parts every chart shares.

Every colour, type style, space and radius on this page is a design-system token, read from the live site. Where a chart needs something the system does not have, it is marked Proposed and collected under Proposed tokens. The written rules behind these specs, including integrity, freshness, layouts and platforms, live in the foundations draft.

Toggle Light and Dark in the top bar: every chart re-resolves its tokens. Hover or tap any mark for its tooltip, or tab to a chart and use the arrow keys.

How to use this page

Each block follows the design system's component shape: a live example, when to use it, anatomy with tokens, settings, states, accessibility, copy, do and don't, and an engineering handoff.

Rules every block on this page follows

• The title is the chart's name. What it shows ("Daily redemptions"), never the finding. The finding goes in aiRA's answer next to the chart, and in annotations and highlights on it.
• Trust line on every chart: the table aiRA queried and the time the query ran, in the org timezone. Nothing else.
• Direct labels first. A key only for colour scales, size, collisions and small multiples.
• Never red on chart marks. Down is --aira-delta-negative orange; red stays for errors.
• View as table on every chart. Card actions appear on hover and keyboard focus, and in a menu on touch; no value lives only in a tooltip.
• One colour means indigo. A single series uses --aira-viz-1; channel colours only appear when channels are compared.
• Hover dims the rest. The active mark keeps its colour and the others fade. No outlines.
• Org locale for every number: this page's demo org is Indian, so lakh, crore and ₹.

Chart card

The frame every chart sits in: title, subtitle, optional key, plot, trust line and actions. It is a composition of AiraCard, so no chart ever needs its own header.

Example

Use when

Anatomy

Behaviour

States

• Loading: AiraSkeleton in the plot's shape with "Drawing this chart…"; title and subtitle already shown.
• No data: the plot area holds a message and a next step, never a blank chart.
• Error: "Couldn't draw this chart", the reason in plain language ("The query took too long to finish."), and Try again. No codes.
• Old snapshot: the card offers Re-run when the result is over 24 hours old.

Accessibility

• The plot is one tab stop with role="img", named by the title and described by a text summary.
• Arrow keys move between values; each is announced ("3 of 6. Koramangala, 11,910 redemptions").
• View as table is a real button with aria-pressed.

Do / don't

Engineering handoff

<AiraChartCard
  title="Redemptions by store"
  subtitle="Redemptions · count · 1–23 Sep 2026 · all tiers"
  source="write_db_100783.redemptions_aira"   // the table aiRA queried
  asOf={queryRanAt}            // formatted in org timezone
  table={rows}                 // powers "View as table" and copy
>
  <AiraBarChart data={rows} xKey="store" yKey="redemptions" highlight="HSR Layout" />
</AiraChartCard>

Chart key

A key makes the reader look away, remember a colour and look back. So the first choice is always a direct label; the key is the fallback, and it has three forms.

Direct labels (the default)

Inline key (paired and stacked charts)

Scale key (colour scales, always shown)

When a key appears

Rules

• Top-left, between subtitle and plot, in a row. Never at the right: aiRA's surfaces are narrow.
• In data order (stack order, or lines by last value). Never alphabetical.
• Clicking an item may highlight that series; it works from the keyboard and never replaces View as table.

Engineering handoff

<AiraChartKey items={[
  { label: "Email", color: "var(--aira-cat-email)" },
  { label: "Push",  color: "var(--aira-cat-push)" },
]} />
<AiraChartKey scale={{ steps: seqTokens(6), low: "Under 20%", high: "60% or more" }} />

Chart tooltip

Adds detail on hover, tap or keyboard focus. It never holds the only copy of a value: anything essential is already on the chart or in View as table.

Example

Anatomy

Behaviour

Engineering handoff

// Built on the AiraTooltip surface; chart blocks render it for you.
<AiraBarChart tooltip={{ rows: ["redemptions"], note: "1–23 Sep 2026" }} … />

Bar chart

The workhorse. Length on a shared baseline is the most accurately read encoding there is, so when the question is "how do these compare", the answer is a bar chart unless something rules it out. AiraBarChart ships today; the variants below are its settings.

Column and horizontal

Paired

100% stacked

Variance

Use when

Variants

Anatomy

Settings

Do / don't

Engineering handoff

<AiraBarChart data={stores} xKey="store" yKey="redemptions" orientation="auto" highlight="HSR Layout" />
<AiraBarChart data={stores} xKey="store" yKey="q2" compare={{ key: "q1", label: "Q1 2026" }} />
<AiraBarChart data={tiers} xKey="tier" series={channels} stack="percent" orientation="horizontal" />
<AiraBarChart data={stores} xKey="store" yKey="vsPlan" variance={{ baseline: "plan" }} better="higher" />

Line chart

The default for anything over time. AiraLineChart ships today; forecast, anomaly markers and moving average are its new settings.

Lines with direct labels

Forecast

More settings, each with its own example: anomaly markers, moving average and reference lines.

Use when

Anatomy

Settings

Rules

• At least two full cycles of history before forecasting; horizon no longer than a third of the history shown.
• aiRA's answer states the forecast range, not only the point.
• Size the chart so the main slope sits near 45°.

Engineering handoff

<AiraLineChart data={months} xKey="month" series={tiers} directLabels />
<AiraLineChart data={months} xKey="month" yKey="redemptions" forecast={{ points: next3, low: "p10", high: "p90" }} today />

Bullet chart

Actual against a target, in a single row per item. It replaces the gauge: same answer, a fraction of the space, and rows compare against each other.

Example

Use when

Anatomy

Settings

Copy

• Title: the chart's name, "Redemption rate against target". aiRA's answer carries the finding: "Only Platinum is above its target."
• Rates compared with rate targets are points, not percent.

Do / don't

Engineering handoff

<AiraBulletChart data={tiers} labelKey="tier" valueKey="rate" targetKey="target" unit="percent" better="higher" />

Waterfall chart

Explains what moved a total from one value to another. The standard answer to "why did revenue change?"

Example

Use when

Anatomy

States

• More than 7 steps: group the smallest into "Other changes".
• A step of zero stays, labelled "0", so the list is complete.

Do / don't

Engineering handoff

<AiraWaterfallChart start={{ label: "July", value: 42.0e5 }} end={{ label: "August", value: 45.1e5 }} steps={drivers} better="higher" unit="currency" />

Funnel chart

Campaign stages from sent to redeemed, as aligned bars on one baseline with the conversion between steps. Never trapezoids: the shape hides the real drop-offs.

Example

Use when

Anatomy

Copy

• Title: the campaign and "funnel". The end-to-end rate or the biggest drop goes in aiRA's answer.
• Stage names in the customer's words, not event names.

Do / don't

Engineering handoff

<AiraFunnelChart stages={stages} labelKey="stage" valueKey="members" />

Heatmap and cohort grid

Two categories and one measure, shown as a grid of cells coloured by value. The cohort variant is the retention triangle every loyalty team asks for.

Example: cohort grid

Use when

Variants

Anatomy

Do / don't

Engineering handoff

<AiraHeatmap variant="cohort" data={cohorts} rowKey="cohort" colKey="month" valueKey="retained" bins={6} unit="percent" />

Scatter chart

Two measures across many items, to see whether they move together and which items stand apart. The bubble variant adds a third measure as size.

Example

Use when

Anatomy

Copy

• The highlighted group is named in an annotation on the chart ("12 high spenders lapsing"), not in the title.
• Always show n. Describe association: "bigger baskets go with more recent purchases", never "recency drives spend".

Engineering handoff

<AiraScatterChart data={members} xKey="daysSince" yKey="basket" highlight={(m) => m.daysSince >= 60 && m.basket >= 6000} sampleSize={72} />

Dot plot and dumbbell

Values as dots on a shared scale. The dumbbell joins two values per row, so the gap is the thing you see.

Example: dumbbell

Use when

Anatomy

Engineering handoff

<AiraDotPlot variant="dumbbell" data={tiers} labelKey="tier" series={[{ key: "email", channel: "email" }, { key: "push", channel: "push" }]} unit="percent" />

Donut and pie charts

Use sparingly. Angle is one of the weakest encodings people read, so a donut or pie is only for two or three parts when the rough proportion is the point. Past three parts it becomes a sorted bar, a 100% stacked bar or a waffle. The donut is preferred: its centre holds the headline total.

Example

Use when

Anatomy

Rules carried from the design system

• Two or three slices only. The agent never draws a fourth; it draws a sorted bar and says why in one line.
• Never 3D, never an exploded (pulled-out) slice, never a second ring.
• A single insight per chart.
• Pie only when there is no total worth showing; otherwise the donut.

Do / don't

Engineering handoff

<AiraDonutChart data={mix} labelKey="type" valueKey="share" total={{ value: 42100, label: "redemptions" }} />

Test result

The result of an A/B or campaign test: each variant's difference from control, with its likely range. It says plainly when a result could be chance.

Example

Use when

States

Anatomy

Copy

• Say "likely range", not "confidence interval"; "could be chance", not "not statistically significant". Technical terms go in the tooltip and the SQL tab.
• Never declare a winner early because a running result looks good.

Engineering handoff

<AiraTestResult metric="redemption rate" unit="points" variants={[{ name: "B · 7 pm reminder", lift: 2.1, low: 1.2, high: 3.0 }, …]} groupSize={12400} status="complete" />

Slope chart

Change between exactly two points, for many items at once. The angle of each line is the change.

Example

Use when

Anatomy

Do / don't

Engineering handoff

<AiraSlopeChart data={tiers} labelKey="tier" from={{ key: "q1", label: "Q1 2026" }} to={{ key: "q2", label: "Q2 2026" }} unit="percent" />

Bump chart

Rank over time. It replaces Power BI's ribbon chart, whose ribbons hide the rank changes they are meant to show.

Example

Use when

Anatomy

Engineering handoff

<AiraBumpChart data={ranks} xKey="month" seriesKey="store" rankKey="rank" highlight="Whitefield" />

Box plot

Compares how values spread across groups: the middle half, the median, the range and the outliers.

Example

Use when

Anatomy

Engineering handoff

<AiraBoxPlot data={baskets} groupKey="tier" valueKey="basket" unit="currency" />

Strip plot

Every value as a dot, grouped by category, with the median marked. The honest alternative to a box plot when readers need to see the actual people.

Example

Use when

Anatomy

Engineering handoff

<AiraStripPlot data={members} groupKey="tier" valueKey="daysBetween" median />

Waffle chart

A single percentage made tangible: 100 squares, one per percent. Reads more naturally than a pie for "how many of every hundred".

Example

Use when

Anatomy

Engineering handoff

<AiraWaffleChart value={38} label="of active members redeemed" />

Treemap

Parts of a whole in a hierarchy, as nested rectangles. For broad patterns, not exact comparison: area is a weak encoding.

Example

Use when

Anatomy

Engineering handoff

<AiraTreemap data={categories} labelKey="name" valueKey="share" childrenKey="kids" />

Pareto chart

Concentration: how few items make most of the total. Bars and the cumulative line share one axis, % of total, so there is no second axis.

Example

Use when

Anatomy

Engineering handoff

<AiraParetoChart data={stores} labelKey="store" valueKey="sales" threshold={80} />

Sankey chart

Movement between states. For loyalty, the question it answers best is who moved up and down a tier.

Example

Use when

Anatomy

Engineering handoff

<AiraSankeyChart flows={migration} sourceKey="from" targetKey="to" valueKey="members" order={tierOrder} colorBy="direction" />

Maps

Where a pattern is geographic. Regions use a tile-grid map by default: one equal square per state, in a rough geographic layout.

Example: tile-grid map

Use when

Anatomy

Variants

Do / don't

Engineering handoff

<AiraMap variant="tiles" layout="india-states" data={states} idKey="code" valueKey="rate" unit="percent" />

Anomaly markers

A line chart setting that marks values outside their expected range. Finding the unusual day is exactly what an analyst like aiRA should do; the chart shows the what, and aiRA's prose offers the possible why.

Example

Rules

• Mark at most three anomalies per chart; more means the expected range is wrong.
• Labels state the fact ("2.3× expected"). A possible cause goes in aiRA's prose, worded as possible ("A preview SMS went out that morning").
• State how "expected" was worked out in the band's tooltip.

Engineering handoff

<AiraLineChart data={days} xKey="day" yKey="redemptions" expected={{ low: "p10", high: "p90" }} anomalies={flagged} />

Reference lines and error bars

What Power BI's analytics pane adds: target, average, median and percentile lines, and error bars for values measured on a sample.

Example

Line styles

Rules

• Two reference lines per chart at most.
• Error bars on any value from a sample: surveys, tests, estimates.
• Say "likely range" in the interface.

Engineering handoff

<AiraBarChart data={tiers} xKey="tier" yKey="nps" errorBars={{ low: "low", high: "high" }} referenceLines={[{ kind: "target", value: 45 }, { kind: "average", value: 41 }]} />

Moving average and calculations

Daily loyalty data swings with the week. A moving average shows the trend underneath without hiding the real days.

Example

Power BI visual calculations, and when each is honest

Engineering handoff

<AiraLineChart data={days} xKey="day" yKey="redemptions" movingAverage={{ window: 7 }} showRaw="context" />

Result tables

How aiRA shows query results as tables in the artifact panel, whether it returns one table or several. The format, tabs and behaviour are the Artifact-preview page's. Alignment follows this page's rule instead: numbers right, words left.

Example

Use when

Anatomy

Alignment

The Artifact-preview page left-aligns every column. This page's rule wins: right-aligned figures line up their place values, so they can be compared down the column.

Behaviour

• One table: no tabs and no cell bar. The table toolbar sits directly above the table.
• Several tables: the first tab is the table that answers the question. Each tab keeps its own page and page size when you switch away and back.
• Paging starts at 10 rows. Changing the page size goes back to page 1, and every page change scrolls the table to its top.
• CSV downloads every row of that table. Copy copies the rows on screen as tab-separated text, and its icon becomes a tick for 1.5 seconds.
• Charts and tables together: the charts come first, then the tables in tabs below them (see Chart preview panel).

States

• Loading: skeleton rows under the real header.
• No rows: "No rows match this query" with the filter or period that caused it, and a way to change it.
• Error: plain language and Try again. No codes.

Accessibility

• Tabs are a tablist; the arrow keys move between tabs.
• Pages are real buttons; the current page carries aria-current="page".
• The page-size menu is a listbox that works from the keyboard: arrows, Enter and Escape.
• Every icon button has an accessible name that includes the table, such as "Copy Points by member".

Do / don't

Scorecard

Several metrics against their targets in one view: Power BI's goals visual, built from a table, bullet bars and sparklines. The standard format for a loyalty programme's monthly review.

Example

Use when

Anatomy

Engineering handoff

<AiraScorecard goals={goals} columns={["value", "target", "progress", "trend", "status"]} />

Matrix

Values across two dimensions with an expandable row hierarchy, as Power BI's stepped matrix does. Every figure is a number, right-aligned; there are no bars inside cells.

Example

Rules

• Group and total rows in --aira-fw-medium; child rows indented by --aira-sp-12.
• Two levels of grouping at most in a chat answer; three on a dashboard.
• No data bars in cells: the percentage alone. If the pattern matters more than the numbers, show a chart instead.
• Conditional colour only as a heatmap table (see Heatmap); never traffic-light cells.

Engineering handoff

<AiraDataTable data={rows} groupBy={["zone"]} expandable columns={[…, { key: "share", unit: "percent" }]} />

Chart preview panel

How several charts, or charts with tables, appear in the preview panel beside the chat on desktop web. Every chart is its own chart card; the panel only arranges the cards. Try every case in the live prototype. Mobile rules come later.

Example

Where charts appear

Layout

How many charts

No count label anywhere: no "5 charts", no "2 charts · 2 tables". The stacked cards already show it.

Order and content

• The chart that answers the question comes first, full width, then the supporting charts.
• Charts before tables. Tables go below the charts in underline tabs, in the Result tables format.
• Every card keeps its full anatomy: title, subtitle with the period, trust line. There is no shared "data from" line for the whole panel.
• One chart per card. A chart with two y-axes becomes two cards on the same months. A grid of subplots becomes one card per chart.
• Preview / Code: Code shows the code aiRA ran. It returns chart data for the product to draw, never an image of the charts.

States

• Drawing: each card shows its title and subtitle, a skeleton in the plot's shape and "Drawing this chart…", and fills in as its own query finishes.
• One chart fails: only that card changes. It reads "Couldn't draw this chart", then "The query took too long to finish.", then a Try again button. The other cards are untouched.

Do / don't

Dashboards

A dashboard is chart cards in a grid, re-run live when it opens. Each tile follows the Chart card block exactly: the same title, subtitle, trust line, actions, hover and full screen as in the preview panel. These rules arrange the tiles.

Reading order

• Header: title, period, filters and the as-of time.
• Row 1: two to four KPI tiles.
• Row 2: the main trend, full width. This is the chart that answers the dashboard's main question.
• Row 3: breakdowns, two or three across.
• Row 4: the detail table, in the Result tables format.

Grid

• 12 columns at lg and xl, 8 at md, 4 at sm.
• Gap between tiles --aira-sp-4; page padding --aira-sp-6.
• Tiles in a row share one height, and their plots share one baseline, so axes line up.
• No chart tile narrower than 4 columns.

Consistency across the page

Limits

• Up to 6 charts visible in one screen at lg, and up to 12 on a dashboard.
• More than that: group them into tabs, one question per tab.
• One highlight colour per dashboard for "this is the story".

Filters and cross-highlighting

• Dashboard filters sit in the header and apply to every tile. Applied filters stay visible as chips, with clear all.
• A tile with its own filter names it in its subtitle ("Gold tier only").
• Changing a filter re-runs the queries and updates every as-of time.
• Clicking a bar highlights that item in every tile; it does not filter. The highlight shows as a removable chip in the header, and Escape clears it.
• Asking a follow-up about a data point opens a new chat, never a conversation inside the dashboard.

Mobile

On iOS and Android, aiRA runs in the phone's browser with the same code as desktop; a native app comes later. Every chart is the same chart card as on web, with the same title, subtitle, plot, key and trust line. Only the controls around the card change for touch. Try it in the live prototype.

Example

What stays the same

• The chart card's anatomy, titles, colours, keys and trust line.
• The Result tables format, alignment by column type, and monochrome cells.
• Loading, error and empty states, word for word.
• The visible size and shape of every button. Only the tap area grows (see Touch targets).

What changes on touch

Touch targets

• Buttons look exactly as on web: 28px on cards, 32px in headers, the same radius and fill.
• Each gets an invisible 44px tap area around it. Neighbouring buttons sit at least 12px apart so tap areas never overlap.
• No hover on touch. A tapped button shows only a pressed state (--aira-bg-pressed) while the finger is down, so it never stays grey.
• Sheets and full screen respect the safe areas (--aira-safe-*) for the notch and the home indicator.

Charts at phone width

• Twelve labelled columns do not fit, so a column chart becomes horizontal bars when its card is narrower than 480px. The data and labels stay the same.
• The month axis shows every second or third month, and the year again wherever it changes.
• Half-width pairing never applies: every chart is full width.
• Direct labels stay; when line ends would collide, they keep at least 15px apart.

Do / don't

Power BI coverage

Every visual on Microsoft's Power BI visualizations overview, checked 23 Sep 2026, and where it lives in aiRA.

Proposed tokens

What this page needs that the design system does not have. On this page they are named --aira-proposed-*, so they can never collide with or redefine a real token.

Orange diverging ramp, as proposed

Divergences found

Places where the live design system disagrees with itself or with the rules on this page. Each needs a decision from the design system owner.

Colour differences measured with a colour-blindness simulation validator (OKLab ΔE × 100); contrast is WCAG contrast against --aira-bg-surface.