Sparks

A spark is a chart the size of a word: no axes, no labels, no legend. Edward Tufte called the line version a sparkline. You make one by writing numbers in ~{…} inside single-backtick inline code:

Weekly signups climbed from 1,200 to 2,050 `~{12 13 12 15 17 16 19 21, end}` in eight weeks.

Like a pill, a spark works on every slide, anywhere inline code can go: a table cell, a kpi line, a caption, a sentence. It belongs beside a current number that has a history, where the history changes how you read the number.

A trend and a plan in every row

Try this. Change Europe's last value to 3.4 and watch its line turn up and its bullet pass the target tick.

How to read a spark

`~{12 14 13 17 21, bar, c3, lg, end}`
   ───────┬──────  ─┬─  ┬─  ┬─  ─┬─
          │         │   │   │    └ marker
          │         │   │   └ size
          │         │   └ color slot
          │         └ type
          └ the data, first in ~{ }

Everything after the data is a modifier, separated by commas inside the braces, in any order: `~{1 3 2, area, c4, lg}` and `~{1 3 2, lg, c4, area}` are the same spark. Leave a modifier out and you get the default.

The data

A series is two to 48 numbers, oldest first: ~{12 14 13 17 21}.
A ratio is one value against a whole or a target: ~{72/80}, or ~{72%} for 72 of 100.

Numbers only. A sign and decimals are fine; units, thousands commas and currency signs are not. The reader’s number is already in the text beside the spark, so the spark only has to carry the shape.

Type

Modifier	Data	Shows	Use it for
(none) for a series, `line`	series	the shape of change	revenue by quarter, weekly signups
`area`	series	the same, with weight	a hero trend under a `kpi` value
`bar`	series	the size of each period	monthly counts
`step`	series	levels that hold, then jump	headcount, a price tier
`winloss`	series	the sign only: hits above, misses below	sprints, quarters beat or missed
(none) for a ratio, `ring`	ratio	one part of a whole	completion, utilization
`bullet`	ratio	a value against a target tick	plan attainment

Every type

Try this. Add lg to one spark, or put a comma in a number and watch it fall back to plain code.

The frame

Every spark sits in a squared frame: a 3:2 tile (a ring’s is square) a step taller than a pill, so it reads as a small chart and never as a label. The frame has three settings, and each one can be set for one spark, one slide or the whole deck:

Setting	Words	Default
Frame	`framed` · `bare` (no frame, just ink in the line)	`framed`
Look	`pigment` · `etching` · `tone` (how the color is spent, below)	`pigment`
Corners	`square` · `rounded` (the theme’s small radius)	`square`

One spark: the word as a modifier, `~{1 3 2, bare}`.
One slide: the word as a class, .
The whole deck: the spark: line in front matter, spark: etching rounded.

The most specific wins, one setting at a time: the spark, then the slide, then the deck. A slide that says spark-bare keeps the deck’s etching and rounded for any spark that asks for its frame back, and a spark that names its own corners asks for it.

Deck, slide and spark settings

Try this. Change the deck's line to spark: tone. The first row changes look; the pigment spark keeps its own.

A frame adds a little height to a line of prose. A paragraph with several sparks may read better with spark-bare on that slide.

Look — `pigment`, `etching` and `tone`

A spark has three parts a color can go to: the tile behind it, the tile’s edge, and the marks (the line, the bars, the ring). A look decides all three at once, from the one color you picked, so a spark stays on brand in every theme and you never mix a fill from one slot with an edge from another. The three looks are the ones Lattice’s charts use, so a spark and a chart beside it speak the same language.

Look	The color goes to	Choose it for
`pigment` (the default)	the tile: the slot’s fill, with the marks in the ink that reads on it	you want color
`etching`	the line: a clear tile, the edge and marks in the slot’s ink, bars a light wash	a modern, lighter look
`tone`	one hue by value: a pale tile, a mid edge and bars, a deep line	a conservative, restrained look

Every look keeps an edge on the tile. A fill on its own is too faint to see against the slide; the edge is what makes the tile visible.

The three looks, one color

Try this. Change every c2 to c7. All three looks follow the new color; none of them needs a second color picked by hand.

In a deck with mode: sketch, sparks are drawn by hand like everything else: the tile’s edge, the line, the bars’ outlines and the ring are sketched in the same pen as the tables around them, and each keeps its look’s colors.

A spark that names no color uses c1, the deck’s first chart color, so it matches the first series of any chart beside it.

Size — `sm`, `lg` and `fill`

A framed spark is measured in a pill’s type size, so it matches the pills around it, and a bare one in the text’s own size. sm and lg step either down and up; widths are fixed per size, so every row’s spark in a table can be compared. fill stretches a spark to the width of its line, for a trend under a big number, and puts it on a line of its own.

Scale — `zero`

A line runs from its own low to its own high, which shows the shape of change. It also makes a series that barely moved look dramatic: churn between 4% and 5% draws as spikes. zero starts the line at zero instead, so the same churn reads flat. Use it when the point is that something held. Bars always start at zero, because a bar’s length is its value.

Markers and color

end dots the latest value in the accent color, so “now” looks the same in every spark.
minmax dots the low and the high.
c1 … c12 are the same numbered color slots pills use. The look decides where the color goes; a bare spark draws in the slot’s color.

When a spark stays code

A mistake shows up as code, not as a wrong chart. A span that opens with ~{, with a digit in its data or a spark modifier beside it, is a spark attempt. If it doesn’t parse, it renders as the code you typed: `~{1,200 1,450}` (a comma), `~{72%, bar}` (a bar needs a series), `~{3 5 4, c13}` (there are twelve slots). lint:deck warns with the reason, and the Studio’s editor underlines the span.

To keep the text on purpose, put a backslash in front: `\~{1,200}` renders as ~{1,200} and silences the warning. LaTeX’s `\~{}` and `\~{n}` have no digit, so they are never read as sparks.

Sparks follow the same switch as pills: inline-code: literal in front matter turns them off for the whole deck.

Writing sparks in the Studio

Type `~ in the editor and a menu offers starter sparks: a line, bars, win-loss, a ring and a bullet. After the closing brace, : offers the next step only: first a type, then a size, then a color, then markers and the frame. Only words that work are offered — one value gets a ring or a bullet, never a line, and a bar is never offered markers. Type something that isn’t in the step on show (c3 while types are listed) and the menu widens to every word that still works, grouped by what it sets.

The Studio also checks each spark’s size against where it landed. A spark that runs past its space, or stands more than one and a half lines of the text around it, pushes its row or paragraph apart. The editor underlines it, says which, and offers a one-click fix to the largest size that fits: a lg spark in a table row usually becomes the default size.

Where sparks belong

Place	How
`kpi`	a supporting line under the value, or `fill` and `area` under the hero number
`table`	a trend column beside the current value, a `bullet` plan column
`big-number`	in the caption, `lg`
a sentence or a list	the default, or `spark-bare` if the lines start to spread

Leave them out of the chart components (a chart inside a chart) and out of chart captions, which stack an inline element on its own row for now.

Every word on one page: the Sparks cheat sheet. Pills are the label-sized sibling: Pills you place. For all three inline elements side by side, see Things you put in a line.