Sediment draws SVG charts in a web page. It is a single JavaScript file with no dependencies and no build step. Copy it into your app, call a builder with your numbers and colours, and it draws the chart inside the element you pass it.
The charts follow a fixed set of drawing rules, listed under Design. The rules work without the code.
Two cards from a personal finance dashboard, drawn from synthetic NZD figures. The second card has a mint background.
Every Sediment chart follows these rules.
- Bands and segments are filled with textures, not colours: squares on a grid or dots on a hex grid. The gap between marks grows with the value, and the largest band is solid. The charts still read in greyscale and for colour-blind readers.
- The data is drawn in one ink colour. A second colour marks a gain or a loss. In the suggested palette, gains are Pistachio and losses are Peach.
- Each line and band is labelled at its right-hand end with its name and latest value. There is no legend.
- With
rangeFrame, the y axis runs only from the lowest value to the highest. Without it, a dotted grid sits behind the data. - A goal, target or limit is a labelled dashed line. An event, such as "now", is a dotted vertical line.
- A missing value leaves a gap in the line. Sediment never draws it as zero.
- Labels use the text colour of the element that holds the chart, and you pass the colour for the marks. To move a chart from a dark card to a light one, swap the two. The image above shows both.
Sediment ships no fonts. Labels use your page's font. The images here use two free Google fonts: Fragment Mono for labels and numbers, because its digits line up, and Rock Salt, a handwritten face, for card titles.
Sediment ships no colours. The images here use four.
| Colour | Hex | Role | Contrast on Chocolate |
|---|---|---|---|
| Mint | #edf3d7 |
ink, marks, lines | 10.7:1 |
| Chocolate | #3e332f |
background | |
| Pistachio | #81bb8b |
gain | 5.48:1 |
| Peach | #e88b7d |
loss | 4.90:1 |
Hairlines are Mint at 50% opacity. On a mint card, Chocolate is the ink and Mint the background. Contrast figures use the WCAG 2 formula.
<link rel="stylesheet" href="sediment.css">
<script src="sediment.js"></script>
<div id="chart" style="color: #edf3d7; background: #3e332f"></div>
<script>
const host = document.getElementById("chart");
const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
const xs = Array.from({ length: 13 }, (_, i) => Date.UTC(2026, i, 1));
const month = t => months[new Date(t).getUTCMonth()];
const saved = [24000, 25500, 27000, 28000, 29500, null, 33000];
const plan = [33000, 37000, 41000, 45000, 49000, 53000, 57000];
const nzd = v => "$" + Math.round(v).toLocaleString("en-NZ");
const nzdK = v => "$" + Math.round(v / 1000) + "k";
Sediment.lineChart({
host, padR: 120, rangeFrame: true,
title: "House deposit, saved and planned",
xs,
series: [
{ values: saved.concat(Array(6).fill(null)), color: "#edf3d7" },
{ values: Array(6).fill(null).concat(plan), color: "#81bb8b", dash: "6 4" },
],
tokens: { axis: "#edf3d7", hair: "rgba(237,243,215,0.5)", page: "#3e332f" },
fmtK: nzdK, fmtValue: nzd,
xLabel: month,
fmtX: t => month(t) + " " + new Date(t).getUTCFullYear(),
endLabel: i => ["saved", "plan"][i],
endValue: i => i ? nzdK(plan[6]) : "",
refs: [{ value: 55000, label: "goal" }],
events: [{ t: xs[6], label: "now" }],
});
</script>The June value is null, so the saved line has a gap there. The plan line is
dashed as well as coloured, so it differs from the saved line in shape. Each line
is labelled at its right-hand end. title, fmtValue and fmtX feed the text
description that screen readers announce (see Accessibility).
There is no npm package. Copy sediment.js and sediment.css into your app
and load them as in the example. sediment.js adds one global,
window.Sediment. Only the svg text rule in sediment.css is required.
Without it, labels render black at the wrong size. The other rules draw the
keyboard focus ring, style the optional data table, and handle forced colours
and reduced motion.
To pull updates, add the repo as a git submodule:
git submodule add https://github.com/jtrotsky/sediment.git vendor/sediment
git submodule update --remote vendor/sediment # later, to updateOpen demo.html in a browser to see every builder draw from live code.
Every builder takes resolved values: CSS colour strings, plain numbers, and
formatter callbacks for text. Sediment never reads your theme, global state or
any DOM beyond the host you give it. You write a thin adapter that resolves
your theme (for example with getComputedStyle) and calls the builders.
Each builder measures the host's width (at least 320 px), clears the host and
appends a fresh <svg>. To redraw, call it again.
Pick by the question, not the shape of the data.
| Question | Builder |
|---|---|
| What changed? | lineChart |
| How has each one moved, when they differ in scale? | smallMultiples |
| What is it made of, and how has that changed? | stackedArea |
| What is it made of, now? | segmentedBar |
| Which is biggest, or how did each month do? | columnChart |
| Where does each one sit on a scale? | dotPlot |
| How far apart are two measures? | barLineChart |
Under about twenty numbers, a table usually beats any of them.
Each is a card from the same personal finance dashboard, with synthetic data in NZD. The company names are made up.
Items on a shared ordinal axis. Position carries the meaning, dot area the amount, and a solid line marks the average. Here each fund sits at its risk level, and the line is the average risk, weighted by value.
Lines over time, each named at its end. Opt in to a range frame
(rangeFrame), latest values (endValue), reference lines (refs) and
events (events). Here net worth is one line, named by its latest value.
Stacked bands over time, each a texture, each labelled on the right with its share and latest value. Here grocery spend splits into five groups. Texture density follows each group's latest value, so only the largest is solid.
Columns on a shared baseline, positive and negative, with an optional target line. Here each month's savings meet a $2,000 target. Months that lost money drop below the line in Peach, and the month still running is faint.
Proportional segments, texture-coded, with optional stepped labels. Here each segment is one holding in a share portfolio, on a mint card.
A textured area for one measure with a line over it for another, so the gap between them reads at a glance. Here the area is the money put into three funds, stacked with one texture each, and the line is what they are worth.
One panel per series on one shared time axis. Use it when series differ in
scale, or when the question is each one's shape. Each panel prints its own min
and max. shared: true puts every panel on one scale. Here a mortgage of about
$400k, drawn in Peach, sits above three balances that grow.
Sediment charts work without colour, without a mouse and without sight.
- Textures and dashes tell series apart, and labels sit on the data. In
forced-colour modes such as Windows high contrast,
sediment.cssdraws everything in the system colours. - Each
<svg>hasrole="img", anaria-labeltaken fromtitle, and a<desc>written from the data. The description gives the chart type, the series, the x range, and each series' latest, lowest and highest value with its date. It also lists reference lines, events and gaps.descreplaces or edits it.table: trueadds the numbers as a collapsed data table. - A chart with a tooltip responds to the keyboard. Tab focuses it, the arrow keys step through points, Home and End jump to the ends, and Escape closes the tooltip. A polite live region reads out each step.
- Sediment animates nothing. Under
prefers-reduced-motion,sediment.cssalso stops any animation the page adds.
Not verified: nobody has tested these charts with a screen reader or in Windows high contrast. The tests check the markup and the key handling in node, against a stand-in for the browser DOM. In NVDA and JAWS browse mode the arrow keys may not reach the chart. The description is in English only.
- Browser only. The builders need a DOM. There is no server-side renderer.
- Monthly time axis. Time-series builders take
xsas epoch milliseconds and tick on month boundaries. - Money defaults.
stackedArealabels values as dollars unless you passfmtNZD.columnChartlabels its baseline$0unless you passzeroLabel. - Tests, but no CI and no releases.
node --test test/a11y.test.jsruns them with nothing to install (Node 18 or later).
Each builder takes one cfg object. host is the element the SVG mounts into,
sized to the host's width. tip is an optional tooltip handle from
Sediment.tip(el).
Every builder also takes these keys (see Accessibility):
title, // accessible name (default: the chart kind)
desc, // string replaces the description, auto => string edits it
fmtValue(v), fmtX(t), // how values and x values read in words
table=false, // true or a summary string: a data table after the chart
keyboard, // default on with a tooltip; true or false to force
dotPlot
host, rowH=22, padT=8, axisPad=30, rightPad=88,
rows:[{ pos, value, label, valueLabel, tipHTML }], // pos = 0..(levels-1)
levels:[str], // axis ticks, left to right
avgPos, // optional average line position
staggerLabels, // two-row axis when labels would collide
dotColor, tokens:{ hair, fg }, tip
lineChart
host, H=230, padL=56, padR=92, padT=14, padB=26,
xs:[t], series:[{ values:[v], color, dash, label }], // null value = gap; label names it in words
tokens:{ axis, hair, page, ref },
fmtK, fmtTick(v, top), rangeFrame=false, xLabel, endLabel, endValue,
refs:[{ value, label, showValue }], events:[{ t, label }],
annotateExtremes, extremeLabel(v, t, kind), tip, tipHTML
The y axis is the dotted grid unless rangeFrame is set, which draws a range
frame instead. fmtTick formats the y ticks and is told which is the top one.
With a range frame the unit can go there once. On the grid every tick counts as
the top one. Lines are solid unless a series sets dash. Extremes are labelled
with fmtK unless extremeLabel is given. Events add 8 px to the top padding
for their labels.
stackedArea
host, H=230, padL=56, padR=110, padT=14, padB=26,
xs:[t], bands:[{ values:[v], ti, label }], n, // ti = texture index
ink, bg, tokens:{ surface, axis, hair, ref },
fmtK, fmtTick, fmtNZD, rangeFrame=false, xLabel, refs, events, tip, tipHTML
fmtNZD formats the value in each band's end label. Without it the label reads
$ and the rounded value.
columnChart
host, H=160, padL=56, padR=12, padT=14, padB=26,
bars:[{ value, label, faint }],
posColor, negColor, ink, tokens:{ border },
target, targetLabel, zeroLabel="$0", tip, tipHTML
segmentedBar
host, barH=24, gap=4, minSeg=24,
segments:[{ label, value, ti, tipHTML }], n, total,
ink, tokens:{ border, hair },
connectors=false, step=30, topPad=14, labelGap=8, tip
barLineChart
host, H=230, padL=56, padR=20, padT=14, padB=26,
xs:[t], bars:[v], line:[v], ti, ink,
areaLabel="area", lineLabel="line", // their names in words
tokens:{ axis, hair, page, ref }, fmtK, fmtTick, rangeFrame=false, xLabel, refs,
events, tip, tipHTML
smallMultiples
host, panelH=56, gap=30, padL=56, padR=92, padB=26,
xs:[t], panels:[{ label, values:[v], color, refs }], shared=false, note,
tokens:{ axis, hair, page, ref }, fmtK, xLabel, tip, tipHTML
Sediment.tip(el)returns{ show(host, x, y, html), hide }, a floating tooltip bound toel. Style it with the.sediment-tiprules insediment.css.Sediment.texture(svg, i, n, ink)is the pattern fill for bandiofn(the last band is solid).Sediment.chip(i, n, ink, size)returns an inline-SVG swatch of that texture for legends and tables.Sediment.describe(svg, { title, desc })gives an SVGrole="img", anaria-labeland a<desc>. Every builder calls it. Call it yourself on an SVG you build withframe().Sediment.valueRanks(values)ranks each value from 0 (smallest) to 1 (largest), so texture density can follow magnitude.Sediment.svgEl,frame,yScale,niceTicks,axisTicks,rangeFrame,grid,monthTicks,placedMonthTicksare the low-level building blocks.
MIT. See LICENSE. The README images embed Fragment Mono and Rock Salt, which keep their own licences.