ZAYAZ ChartsData Structure
This directory contains all static chart configuration and demo data used in the ZAYAZ Developer & Docs site.
- Charts are rendered with Apache ECharts via
echarts-for-react. - Each JSON file in this tree contains a complete ECharts
optionobject. - MDX pages load these options and pass them to the shared
<ZayazEChart />wrapper (which applies the globalzayazECharts theme).
The goal is:
- Single, centralized source of example chart configs
- No inline data blobs in MDX
- Consistent visual language across clients / validators / authorities / internal docs
- Zero risk of leaking real data (all content here must be synthetic/anonymized)
1. Folder Layout
The folder structure mirrors the main ZAYAZ architecture and use cases:
src/components/chartsdata/
common/ # Reusable or utility configs (if needed later)
input-hub/
computation-hub/
reports-insights-hub/
sis/ # Shared Intelligence Stack
gamification/
academy/
external-systems/
Each top-level folder can have subfolders by domain or metric group, for example:
reports-insights-hub/
trust/
trust-trend-client.json
trust-trend-validator.json
trust-trend-authority.json
csrd/
coverage-radar-client.json
gap-matrix-authority.json
materiality/
matrix-client.json
matrix-validator.json
Rule of thumb: Folder path encodes module / domain, filename encodes chart type + audience.
⸻
2. Naming Convention for JSON Files
We use a simple, consistent pattern:
<chart-key>-<audience>.json
Where:
chart-key= a short kebab-case identifier for what the chart shows- Examples: trust-trend, coverage-radar, validation-heatmap, materiality-matrix, spend-vs-ghg, peer-confidence-band, impact-polar.
audience= the primary reader/context for this version of the chart:- client
- validator
- authority
- internal (for Viroway-only docs)
Examples:
- trust-trend-client.json
- trust-trend-validator.json
- coverage-radar-authority.json
- materiality-matrix-client.json
- spend-vs-ghg-rainfall-client.json
- peer-confidence-band-validator.json
- impact-polar-internal.json
If you ever need versioning, use:
<chart-key>-<audience>-v2.json
…but try to keep one canonical file per chart + audience.
⸻
3. JSON File Content
Each file contains a single ECharts option object, e.g.:
{
"title": {
"text": "Trust Score Trend (Demo)",
"left": "center"
},
"tooltip": { "trigger": "axis" },
"xAxis": { "type": "category", "data": ["2025-Q1", "2025-Q2", "2025-Q3", "2025-Q4"] },
"yAxis": { "type": "value", "min": 0, "max": 100 },
"series": [
{
"type": "line",
"name": "Trust Score",
"data": [72, 79, 85, 90]
}
]
}
3.1 Required characteristics
- Must be valid ECharts option JSON.
- Self-contained: no functions, only JSON-compatible types.
- Any dynamic logic (e.g. positive/negative colour functions) is added in the MDX/TS layer, not in JSON.
- No real or sensitive data — all values are synthetic or safely anonymized.
- Use CSS variables for colours (not hard-coded hexes) whenever possible.
3.2 Styling: rely on theme, only override semantics
We use a global ECharts theme – zayaz – which already sets default:
- font family (Zayaz Public Sans)
- grid layout
- axis styles
- base palette
- basic chart styles for:
- line, bar, radar, pie, gauge, sankey, scatter, heatmap, treemap, boxplot, calendar, polar, etc.
In JSON files:
- Do not restyle everything.
- Only specify what is semantically important, such as:
- Positive vs negative value colouring
- Currency series (SLATE BLUE)
- Good vs bad risk areas
- Different series categories
Example (good):
{
"series": [
{
"type": "bar",
"name": "Spend (€)",
"data": [120000, 180000, 90000],
"itemStyle": {
"color": {
"type": "linear",
"x": 0, "y": 0, "x2": 0, "y2": 1,
"colorStops": [
{ "offset": 0, "color": "var(--color-slate-400)" },
{ "offset": 1, "color": "var(--color-slate-600)" }
]
}
}
}
]
}
⸻
4. Semantic Colour Rules
4.1 Positive vs Negative values
We use:
- SUCCESS (green) for positive / good values
- WARNING (amber) or ERROR (red) for negative / problematic values, depending on severity.
Relevant CSS tokens from custom.css:
- Green: --color-green-400, --color-green-500, --color-green-600
- Amber: --color-warning-400, --color-warning-500, --color-warning-600
- Red: --color-error-400, --color-error-500, --color-error-600
Because JSON cannot contain JS functions, we generally:
- Use two separate series (one for positive, one for negative) if we want distinct colours, or
- Let the React layer apply a colour function for advanced logic.
Document-level pattern (for reference):
Positive / improvement: var(--color-green-500) Negative / regression: var(--color-warning-500) (or --color-error-500 for critical)
4.2 Currency values
Any series that represents money (€, $, etc.) should use the SLATE BLUE palette:
- --color-slate-400, --color-slate-500, --color-slate-600
Example (in JSON):
{
"series": [
{
"name": "Spend (€)",
"type": "bar",
"data": [120000, 180000, 90000],
"itemStyle": {
"color": {
"type": "linear",
"x": 0, "y": 0, "x2": 0, "y2": 1,
"colorStops": [
{ "offset": 0, "color": "var(--color-slate-400)" },
{ "offset": 1, "color": "var(--color-slate-600)" }
]
}
}
}
]
}
This creates a visual language: SLATE = money.
⸻
5. Chart Types & Typical Content
Each JSON file defines one chart. Below are guidelines for what each type usually contains.
5.1 Donut / Pie
Typical use: proportions (data provenance, verified vs unverified, spend categories).
Key properties:
series[0].type = "pie"series[0].radius = ["40%", "70%"](donut style)series[0].datais an array of objects like{ value, name }- Optional gradient
itemStyle.colorper slice for visual richness.
Location example:
- reports-insights-hub/eco-number/eco-score-distribution-client.json
https://echarts.apache.org/examples/en/editor.html?c=pie-borderRadius
⸻
5.2 Gauge
Typical use: ECO Score, Trust Score, Index-style metrics.
Key properties:
- series[0].type = "gauge"
- series[0].min, max, data[0].value
- Title and detail text for label/score.
Location example:
- reports-insights-hub/trust/trust-gauge-client.json
https://echarts.apache.org/examples/en/editor.html?c=gauge-grade
⸻
5.3 Sankey
Typical use: value chain flows, Scope 3 emissions flow, signal routing.
Key properties:
series[0].type = "sankey"series[0].data(nodes) andseries[0].linksas an array of{ source, target, value }objects.
Location example:
- computation-hub/validation/signal-flow-sankey-internal.json
https://echarts.apache.org/examples/en/editor.html?c=sankey-itemstyle
⸻
5.4 Scatter (Materiality Matrix)
Typical use: impact vs likelihood, risk quadrants.
Key properties:
- series[0].type = "scatter"
- series[0].data = [impact, likelihood, label?]
- X/Y axes from 0–1 or 0–100.
Location example:
- reports-insights-hub/materiality/materiality-matrix-client.json
https://echarts.apache.org/examples/en/editor.html?c=scatter-clustering
⸻
5.5 Heatmap
Typical use: metric completeness, evidence coverage, validation intensity.
Key properties:
- series[0].type = "heatmap"
- series[0].data = [xIndex, yIndex, value]
- visualMap with colour range (often green → amber → red).
Location example:
- computation-hub/validation/validation-heatmap-validator.json
https://echarts.apache.org/examples/en/editor.html?c=heatmap-cartesian
⸻
5.6 Treemap
Typical use: signal origins, NACE breakdown, metric hierarchies.
Key properties:
series[0].type = "treemap"series[0].datais a nested tree-like structure with fieldsname,value, and optionalchildren(array).
Location example:
- sis/signals/signals-treemap-internal.json
https://echarts.apache.org/examples/en/editor.html?c=tree-orient-right-left&lang=js
⸻
5.7 Boxplot
Typical use: peer distributions (e.g. emissions per revenue), outlier detection.
Key properties:
- series[0].type = "boxplot"
- Data typically pre-processed by ECharts “boxplot” transform, but for docs you can store already-computed arrays.
Location example:
- reports-insights-hub/benchmark/ghg-intensity-boxplot-validator.json
https://echarts.apache.org/examples/en/editor.html?c=data-transform-aggregate
⸻
5.8 Calendar Heatmap
Typical use: daily activity, reporting frequency, telemetry intensity, GHG emission.
Key properties:
- calendar object (range, cellSize)
- series[0].type = "heatmap"
- series[0].coordinateSystem = "calendar"
Location example:
- sis/audit/audit-calendar-heatmap-internal.json
https://echarts.apache.org/examples/en/editor.html?c=calendar-vertical
⸻
5.9 Timeline (simple line/step chart)
Typical use: trust, completeness, or events over time.
Key properties:
- xAxis.type = "category" with time labels
- series[0].type = "line" or "bar"
- Optional markPoint or axisPointer.
Location example:
- reports-insights-hub/trust/trust-timeline-authority.json
https://echarts.apache.org/examples/en/editor.html?c=line-smooth
https://echarts.apache.org/examples/en/editor.html?c=area-simple
⸻
5.10 Rainfall (Spend vs GHG reduction)
Typical use: show effect of spend on GHG reduction (two-axis chart).
Key properties:
- yAxis[0] = currency
- yAxis[1] = GHG delta (%)
- Series 1: SLATE BLUE bars for spend
- Series 2: line for GHG delta (green for negative/reduction, amber/red if emissions increase).
Location example:
- reports-insights-hub/finance/spend-vs-ghg-rainfall-client.json
https://echarts.apache.org/examples/en/editor.html?c=area-rainfall
⸻
5.11 Confidence Band (peer group vs company)
Typical use: show company vs peer range (e.g. decarbonisation trajectory).
Key properties:
- One or two line series with areaStyle to create a band.
- One line series for the company.
Location example:
- reports-insights-hub/benchmark/peer-confidence-band-validator.json
https://echarts.apache.org/examples/en/editor.html?c=confidence-band
⸻
5.12 Polar Bar (impact vs peers)
Typical use: “biggest to smallest impact” for categories, with peer comparison.
Key properties:
- coordinateSystem = "polar"
- angleAxis with categories
- radiusAxis for values
- One or more bar series.
Location example:
- reports-insights-hub/impact/impact-polar-internal.json
https://echarts.apache.org/examples/en/editor.html?c=bar-polar-label-tangential
⸻
5.13 Various
⸻
6. Using ChartsData in MDX
Pattern inside an MDX docs page:
import BrowserOnly from '@docusaurus/BrowserOnly';
import { ZayazEChart } from '@site/src/components/ZayazEChart';
<BrowserOnly>
{() => {
const option = require('@site/src/components/chartsdata/reports-insights-hub/trust/trust-trend-client.json');
return <ZayazEChart option={option} />;
}}
</BrowserOnly>
This:
- Loads the JSON option at runtime.
- Ensures ECharts only renders in the browser (BrowserOnly).
- Uses the shared ZayazEChart wrapper, which:
- Registers the zayaz theme once
- Applies consistent sizing and performance flags.
⸻
7. Rules & Best Practices
- Always synthetic data in this directory.
- Use CSS colour variables from custom.css instead of raw hex codes, wherever possible.
- Keep filenames short but descriptive (trust-trend-client.json, not trust-score-evolution-line-chart-for-client-users.json).
- For the same chart across audiences, reuse the same chart-key and change only the -
-audiencesuffix. - If a chart becomes obsolete, delete the JSON file and update any MDX docs that reference it.
- When in doubt:
- Put heavy logic in TypeScript,
- Keep JSON simple, static, and readable.
⸻
If you add new chart types or domains, follow the same pattern: folder = module/domain, file = chart-key + audience, content = one ECharts option object.