# ELECT

A framework-neutral data-visualization design system: a CSS token layer (`--elect-*`), a Color
Engine that derives those tokens from **one brand color — guaranteed accessible** (contrast and
colorblind distinctness), and Web Components that read them.

**"Agnostic" means the token layer doesn't dictate your renderer — NOT that any chart library picks
it up automatically.** Two ways in:
1. **ELECT's own components** (Web Components) read the tokens themselves — batteries included.
2. **Your own SVG/DOM renderer** (Recharts, raw SVG, D3-on-SVG): you wire `var(--elect-*)` into it —
   small but real glue. **Canvas renderers** (Chart.js, ECharts) can't read CSS variables; read the
   computed value in JS and pass it in.

**Start here:** open [`playground/index.html`](playground/index.html) (double-click, no server) — set
your brand color (and, under "More tokens", your design system's colors and font), see every chart
re-theme, export what you need.

> Docs: [`ARCHITECTURE.md`](ARCHITECTURE.md) (the code contract) · [`STRATEGY.md`](STRATEGY.md)
> (decisions) · [`DECISIONS.md`](DECISIONS.md) (decisions log) · specs:
> [`SPEC-bar-chart.md`](SPEC-bar-chart.md), [`SPEC-line-chart.md`](SPEC-line-chart.md), [`SPEC-waterfall.md`](SPEC-waterfall.md).

---

## Use it in 10 minutes

### 1 · Tokens (2 min) — pick one
- **Live, from a brand color:** load the engine and apply a theme where you want it
  (`:root`, or any container):
  ```html
  <link rel="stylesheet" href="elect/tokens/base.css">
  <script src="elect/engine/color-engine.js"></script>
  <script>Elect.applyTheme(Elect.generateTheme('#0b6e4f'), document.documentElement);</script>
  ```
- **Static, zero runtime JS:** generate the theme once and ship a CSS file:
  ```sh
  node tools/elect-theme.js --brand "#0b6e4f" --out elect-theme.css            # CSS
  node tools/elect-theme.js --brand "#0b6e4f" --surface dark --selector ".dark" --out elect-dark.css
  node tools/elect-theme.js --brand "#0b6e4f" --format dtcg --out elect.tokens.json   # W3C DTCG
  ```
  then `<link rel="stylesheet" href="elect/tokens/base.css"><link rel="stylesheet" href="elect-theme.css">`.
  (Or copy the "Theme tokens (CSS)" block from the playground.)

Density: put `data-elect-density="compact|normal|spacious"` on `:root` or any container.

### Inside your design system
The charts usually sit **in your cards**, on your page. Give ELECT your values and it derives the rest
against them — the palette, the outlines, every text shade, all kept accessible.

1. **Playground → Brand color:** your primary (any CSS color: `#0f62fe`, `rgb()`, `hsl()`, `oklch()`…).
2. **More tokens:** **Background** = your *card* color (what the charts sit on) · **Success / Danger** =
   your good / bad colors (one under 4.5:1 as text is corrected, and the panel says so; "Keep my
   original" overrides) · **Font** — leave **Auto** and the charts wear your page's font.
3. **Cards → Off:** your cards are the frame; ELECT draws none. The charts then sit exactly on your
   Background.
4. **Export → Map to your tokens:** under each color, type your design system's token for it
   (`--color-primary`…) and each value is written as `var(--yours, value)`, so it follows your theme.
   Then pick HTML · Web Components or React and the charts, and Download (one file; "View code" shows it).
   - Colors stored as bare channels (shadcn: `--primary: 222 47% 11%`) → write `hsl(var(--primary))`.
   - **Where your tokens live:** the element that carries your variables. If your design system puts
     its theme on a class (`<body class="cds--g100">`, `.dark`), type that selector (or `body`) — a
     variable is read where the theme is declared, and `:root` can't see a class below it.
   - Export once per mode (light / dark) and scope each to its class.

Static, the same: `node tools/elect-theme.js --brand "#0f62fe" --background "#f4f4f4" --card none`.
Five real design systems wired this way (Carbon, Polaris, Radix, Atlassian, shadcn):
[`proof/integration/`](proof/integration/index.html).

### 2 · A chart (3 min)
```html
<script src="elect/components/elect-core-paint.js"></script>  <!-- always first, in this order -->
<script src="elect/components/elect-core.js"></script>
<script src="elect/components/elect-bar-chart.js"></script>

<elect-bar-chart mode="grouped" show-values style="display:block;height:320px"
  series='["2025","2026"]'
  data='[{"label":"Q1","values":[120,150]},{"label":"Q2","values":[98,112]}]'>
</elect-bar-chart>
```
From JavaScript, set properties instead: `el.series = [...]; el.data = [...]` — a new `data` array
makes the bars **glide** to their new values.

### 3 · Listen (2 min)
Every chart emits `*-hover` / `*-select` events (bubbling, composed) with
`{ index, categoryIndex, seriesIndex, series, label, value }` — **you** own the tooltip.
```js
chart.addEventListener('bar-hover', (e) => showTooltip(e.detail));
```

---

## The components

| Element | File | Data | Main options |
|---|---|---|---|
| `<elect-bar-chart>` | `elect-bar-chart.js` | `[{label, value}]` or `[{label, values:[…]}]` + `series` | `orientation` vertical/horizontal · `mode` single/grouped/stacked · `show-values` `show-grid` `show-axis` · `overflow` scroll/fit · `max` · `radius` |
| `<elect-line-chart>` | `elect-line-chart.js` | same shapes | `baseline="fit"` · `area` (≤ 2 series) · `layout="multiples"` · `show-values` |
| `<elect-donut>` | `elect-donut.js` | `[{label, value}]` | `variant="pie"` · `sort="none"` · `show-total="false"` |
| `<elect-heatmap>` | `elect-heatmap.js` | rows `[{label, values:[…]}]` + columns in `series` | `scale="diverging"` · `center` · `show-values` |
| `<elect-combo>` | `elect-combo.js` | grouped shape + `kinds` | `secondary-axis` (both from 0, aligned gridlines) |
| `<elect-scatter>` | `elect-scatter.js` | `[{x, y, size?, group?, label?}]` | `x-label` `y-label` · `zero` |
| `<elect-histogram>` | `elect-histogram.js` | `el.values = [...]` or `[{from, to, count}]` | `bins` · `bin-width` · `x-label` |
| `<elect-waterfall>` | `elect-waterfall.js` | `[{label, value, total?}]` — a step, an anchored total, or a computed subtotal | `orientation` · `good-direction` up/down/none · `show-values="false"` · `connectors="false"` · `overflow` |
| `<elect-kpi>` | `elect-kpi.js` (no core needed) | attributes | `label` `period` `value` `delta` `comparison` · `direction` · `good-direction="down"` · a second comparison: `delta-2` `comparison-2` `direction-2` · `trend="1,2,3"` |

All charts: `animate="false"`, `slot="legend"` for your own legend, keyboard navigation, a hidden
data table for screen readers, `null` / non-numeric = "missing" (never drawn as 0), and the
palette cap (6 colors — more series become neutral / "Other" / small multiples).

## Frameworks

Web Components work in every framework as plain elements — **no wrapper needed** except to pass
arrays as properties and to listen to events the framework's way.
- **React:** `wrappers/elect-react.js` → `const { BarChart } = ElectReact.create(React)`;
  `<BarChart data={rows} series={names} mode="grouped" onBarHover={fn} />` (React ≥ 16.8).
- **Vue 3:** `<elect-bar-chart :data.prop="rows" :series.prop="names" @bar-hover="fn" />`
  (tell Vue the tag is custom: `app.config.compilerOptions.isCustomElement = (t) => t.startsWith('elect-')`).
- **Svelte:** `<elect-bar-chart data={rows} series={names} on:bar-hover={fn} />` (Svelte sets
  properties on custom elements when they exist).
- **Angular:** add `CUSTOM_ELEMENTS_SCHEMA`; `<elect-bar-chart [data]="rows" [series]="names" (bar-hover)="fn($event)">`.
- **Plain HTML / server-rendered:** the JSON `data` / `series` attributes, as above.

## Tests

`node tests/run.js` — every chart rendered in real headless Chrome and compared to golden snapshots, plus
the rules that must always hold (contrast, null ≠ 0, stable palette, …). See [`tests/README.md`](tests/README.md).

## Repo map

```
tokens/base.css          Base tokens (CSS variables) — the universal language.
engine/color-engine.js   Color Engine: brand → accessible palette (contrast + colorblind distinctness).
components/              elect-core-paint.js + elect-core.js (shared chart core) + one file per component.
wrappers/elect-react.js  React bindings.
tools/elect-theme.js     Static theme export (CSS / DTCG JSON), zero runtime JS.
playground/              The product playground (Phase 3).
proof/                   Live test benches, one per component (proof-1 = color-engine.html).
tests/                   Golden snapshots + invariants (node tests/run.js).
vigit/                   Visual history: frozen polaroids, one per delivery milestone.
```

## License

[MIT](LICENSE) — free to use, change and ship, in any project, as long as the copyright notice stays with it.

Third-party: the site's icons are from [Phosphor Icons](https://phosphoricons.com) (MIT, © 2023 Phosphor Icons);
the site's font, Switzer, is loaded from Fontshare (Indian Type Foundry's free license) and is not part of ELECT — the
charts wear your page's font.
