Custom chart build
A custom chart is a template that turns query rows into SVG. The engine
renders it, checks the output, and frames it like every other chart: the
title and subtitle above, the board's card padding around, the chart-root
link: honored. Reach for it last: a built-in chart gets axes, legends,
hover, sizing rules and visual warnings for free; a custom chart draws only
what its template draws.
1. Check what the project already has
dct describe templates/ # every template: description, channels, options
dct describe templates/funnel.svg.j2
dct examples charts/custom-inline # a complete inline board to copy
A template: name with no file lists the templates the project does have.
2. Author the chart
queries:
stages:
columns: [stage, visitors]
values:
- [Visited, 4200]
- [Signed up, 3100]
- [Upgraded, 740]
charts:
signup_flow:
type: custom
query: stages
# template: funnel # templates/funnel.svg.j2, or the template inline
svg: | # under svg: (exactly one of the two)
{#---
description: One bar per stage, each a link.
channels:
x: {}
y: {}
options:
bar_height:
type: integer
default: 24
---#}
{% set top = rows | map(attribute=channels.y) | max %}
{% for r in rows %}
<a href="{{ href(r) }}">
<rect y="{{ loop.index0 * (options.bar_height + 8) }}" height="{{ options.bar_height }}"
width="{{ r[channels.y] / top * width }}" fill="{{ style.fonts.secondary.color }}"/>
</a>
{% endfor %}
title: Where visitors go
x: stage # channels sit at the chart root, as on any chart
y: visitors
options:
bar_height: 24 # the template's own settings
link: /boards/stage/{{ x }} # optional: a click-through, like every chart
style:
aspect_ratio: 2 # sizing only: aspect_ratio, min_height, max_height
rows:
- signup_flow
Channels use the built-in names (x, y, color, size, shape, theta,
value); pick the role a built-in chart would use (a funnel's stage is x,
its count y; a waffle's parts are color and theta). Everything else the
template needs goes under options:. The look comes from the board's
style:, never from the chart.
Let the query do the math. Sorting, ranking, shares, running totals and
binning belong in SQL; the template loops and draws, mapping data to pixels
with d3 scales rather than inline arithmetic.
3. Declare the header (template files)
A template file opens with a YAML header in a Jinja comment. It is the
contract the chart's channels and options are validated against at compile:
{#---
description: Flow diagram from an edge list.
channels:
x:
description: Source node, then target node.
multiple: true
value:
description: Size of each flow.
options:
node_width:
type: number
default: 12
---#}
No default means required; default: null means optional (none in the
template). Option types: column, columns, string, number, integer,
boolean, color. An inline svg: template takes the same header; without
one it declares no channels or options and reads columns by name (r.revenue).
4. What the template sees
| Name |
Holds |
rows |
The query result, one mapping per row. A chart with no query: gets []. |
columns |
The result's column names, in order. |
channels |
Declared channel to column: channels.x is a column name, a list for a multiple channel, none when optional and unset. |
options |
The chart's options with the header's defaults filled. |
width, height |
The drawing box in pixels: inside the card padding, below the title. Draw from (0, 0) to (width, height). |
uid |
A prefix unique to this chart; use it for every id (id="{{ uid }}-clip") so two charts on one board never collide. |
style |
The board's merged style tree, every color a hex value: style.font.family, style.font.color, style.fonts.secondary.color, style.tones.positive, style.charts.color.categorical.palette, style.charts.axis.grid.color, style.palettes.<role> (a list of colors, or a mapping of stops for a tone). |
variables |
The board's variable values for this render (variables.region). |
math |
sin, cos, tan, asin, acos, atan2, sqrt, log, exp, floor, ceil, pi, tau. Radians. Write a negative angle as -1 * math.pi / 2: -math.pi negates math. |
d3 |
d3's scales, ticks, path generators, pie, stack and sankey layouts, symbols, format, color interpolators and schemes, geo projections and geo_path, in snake_case (below). |
Helpers:
| Helper |
Returns |
value | format('.1%') |
The value through a d3-format spec, the same specs format: takes elsewhere. |
value | format(column=channels.y) |
The value through the format the board resolved for that column: the query's formats:, style.formats, the number locale and currency, the way a KPI prints it. Prefer it to a value_format option that only restates the column's format; keep an option only when the template should print something different. A spec and column= together is an error, as is a column the query did not return. Numbers only: a date or text value under column= is an error. With no rows there are no columns: wrap a derived total in {% if rows %}. |
text_width(text, size, weight) |
Pixel width of text in the board's font at size; weight optional (600, "bold", or any weight style carries). Digits measure as tabular numerals, like the axis labels the engine draws. Measure labels instead of guessing. |
color_for(value, column) |
The board's pinned color for that column's value (style.charts.category_colors), else the next categorical palette color; stable within a chart. |
label_ink(color) |
color as text ink on the chart's background: the engine's dark step with a 4.5:1 floor, right on light and dark themes. |
variant(color, kind) |
light, dark, pale or deep tier of a hex color; the engine's palette-variant math. |
href(row) |
The chart's link: for that row, every {{ channel }} placeholder filled from the row. |
raise_error(message) |
Stops the render and shows message in the chart's place. Use it for data the template cannot draw. |
d3 replaces the arithmetic a template would repeat, and draws with the same
numbers the built-in charts use. Arguments go by position or keyword; a
zero-width domain, a non-numeric value or an unknown curve fails the chart
with an error naming the call.
d3 function |
Returns |
d3.scale_linear(domain, range) |
A scale for two-number lists. x(v) maps, x.invert(px) maps back, x.domain and x.range read the ends, x.nice(count=10) returns a new scale with round ends, x.ticks(count=10) the tick list, x.tick_format(count=10, spec=none) a function printing a value at the ticks' precision through the board's number locale (spec is a d3-format spec). |
d3.scale_sqrt(domain, range) |
The same, range proportional to the square root of the value: radius from a value so area follows it. |
d3.scale_log(domain, range, base=10), d3.scale_pow(domain, range, exponent=1), d3.scale_symlog(domain, range, constant=1) |
The same methods. A log domain must not cross or touch zero; exponent is not zero; constant is positive. A log scale's tick_format prints "" for the ticks d3 thins from a crowded decade, and a value with no position (log of 0) is an error. |
d3.scale_band(domain, range, padding=0, padding_inner=0, padding_outer=0, align=0.5) |
Names to bands: b(name) is the band start, b.bandwidth() the width, b.step() the pitch; padding= sets both paddings. A name outside the domain is an error. |
d3.scale_point(domain, range, padding=0, align=0.5) |
Names to points: p(name) is the position (one point sits at the range's center), p.step() the pitch; padding= is the outer padding. A name outside the domain is an error. |
d3.line(points, curve="linear"), d3.area(points, y0, curve="linear") |
A path d through [x, y] pairs; area closes down to the line at y0. Curves: linear, monotone_x, monotone_y, step, step_before, step_after, basis, natural, cardinal. |
d3.arc(inner_radius, outer_radius, start_angle, end_angle, pad_angle=0, corner_radius=0) |
A sector path d centered on the origin; angles in radians clockwise from twelve o'clock; place it with transform="translate(cx, cy)". |
d3.pie(values, start_angle=0, end_angle=math.tau, pad_angle=0) |
A list of {index, value, start_angle, end_angle, pad_angle} in data order (no default sort: order in the query), ready for d3.arc. |
d3.geo_mercator(), d3.geo_equal_earth(), d3.geo_orthographic(), d3.geo_albers_usa(), d3.geo_identity(), … (every d3-geo projection, snake_case) |
A projection: p([lon, lat]) maps (none where the projection has no place for the point), p.invert([x, y]) maps back. Settings are methods that read with no argument and return a new projection with one: scale, translate, center, rotate, parallels, clip_angle, clip_extent, precision, angle, reflect_x, reflect_y; fit_size([w, h], geojson) (also fit_extent, fit_width, fit_height) scales and translates to show the object in the box. |
d3.sankey(links, nodes=none, size=none, extent=none, node_width=24, node_padding=8, align="justify", iterations=6) |
d3-sankey's layout over {source, target, value} links (nodes named by string or number, in order of first appearance unless nodes lists them; size=[w, h] is the box). Returns {nodes, links}: nodes carry name, index, value, depth, height, layer, x0, x1, y0, y1, source_links, target_links; links index, source, target (the node mappings), value, width, y0, y1. A cycle is an error. |
d3.sankey_link_horizontal(link) |
The d of a link's centerline; stroke it with stroke-width="{{ link.width }}", fill="none". Printed the way the engine prints every chart's path (two decimals at most). |
d3.stack(series, order="none", offset="none") |
d3-shape's stack() over series[i][j] (lists of equal length; none for no datum). Returns {series, index}: series[i][j] is [y0, y1] (none for no datum) and index[i] the series' place in the order. order: none, ascending, descending, inside_out, reverse, appearance; offset: none, expand, diverging, silhouette, wiggle. |
d3.symbol(type="circle", size=64) |
d3-shape's symbol d, size square pixels, centered on the origin: circle, cross, diamond, square, star, triangle, wye to fill; plus, times, triangle2, asterisk, square2, diamond2 to stroke. Printed the way the engine prints every chart's path (two decimals at most). |
d3.format(spec) |
The format filter as a function: d3.format('$,.0f')(v) prints through the board's number locale. |
d3.scale_utc(domain, range) |
scaleUtc for two instants (milliseconds or ISO-8601 text, a bare clock is UTC) and a two-number range. x(t) maps, x.invert(px) gives milliseconds, x.domain (ms) and x.range read the ends, x.ticks(count=10) the tick instants in ms, x.nice(count=10) a new scale with round ends, x.tick_format(count=10, spec=none) a function printing an instant in UTC through the board's time locale (d3's multi-scale format, or a d3-time-format spec). |
d3.time_format(spec), d3.time_parse(spec) |
utcFormat and utcParse through the board's time locale: d3.time_format('%b %d')(t) prints an instant (ms or ISO text) in UTC, d3.time_parse('%d.%m.%Y')(text) gives ms or none. |
d3.interpolate_rgb(a, b), d3.interpolate_hcl(a, b) |
A function of t in [0, 1] mixing two colors (hex, rgb(), hsl(), CSS name), printed as rgb(r, g, b). |
d3.scheme_category10, scheme_accent, scheme_dark2, scheme_paired, scheme_pastel1, scheme_pastel2, scheme_set1, scheme_set2, scheme_set3 |
d3-scale-chromatic's categorical schemes, lists of hex colors. Prefer style.charts.color.categorical.palette or color_for so colors follow the theme. |
d3.geo_path(projection=none, digits=3, point_radius=4.5) |
d3's geoPath: path(geojson) is the d of a GeoJSON mapping (Feature, FeatureCollection, a geometry, {"type": "Sphere"}) or its JSON text, or none when nothing is drawn (a point behind the globe); path.area, .bounds, .centroid, .measure take the same object. The projection clips: a graticule or a point on the far side simply ends. |
Names are strict: a misspelled column, option or style key fails the chart
and names the template line. Output is escaped, so a label with < draws as
text.
5. Links
Set link: on the chart like any other chart:
- A link with no
{{ channel }} placeholder wraps the whole drawing in one
anchor; the template draws nothing extra.
- A link with placeholders (
/boards/stage/{{ x }}) is per row: the template
wraps the marks it wants clickable in <a href="{{ href(r) }}">...</a>. A
template that never calls href under such a link fails the chart.
Board paths resolve against the host; http, https and mailto pass
through; anything else is refused.
6. Fonts and theme
Read fonts and colors from style rather than writing them in:
font-family="{{ style.font.family }}" paints the board font, and an export
embeds that font file exactly as it does for built-in charts. A template
that reads only style follows every theme, dark ones included.
7. Where the drawing lands
The engine draws the title and subtitle, then places the template's output
in a group translated below them, inside the card's padding. width and
height are that box, so a template never allows for the title or padding
itself. Output outside that box is clipped. A template that wants the full
card height omits title:.
8. What the output may contain
Well-formed SVG from drawing elements only: shapes (rect, circle,
ellipse, line, polyline, polygon, path), text (text, tspan,
textPath), grouping (g, defs, symbol, use), paint
(linearGradient, radialGradient, stop, pattern, clipPath, mask,
marker), title and desc (a <title> inside a shape is a native browser tooltip, not the board's tooltip card),
and a with an href the link rules above accept.
Refused, never stripped (ERR-CUSTOM-SVG names the construct): script,
foreignObject, style, image, filter (shadow and blur and raster images
stay unsupported: vector-only, sandboxed output), animation elements, on* attributes, the
board's own hooks (role, aria-*, data-*, classes starting with role-
or dbt-), a paint attribute that is not a color or url(#id), an href or
url() that is not #local outside <a>, javascript:, CSS escapes and
loading functions, a null interpolated into an attribute, nesting past 64
levels, comments, processing instructions,
CDATA, DOCTYPE.
9. The template dialect
The engine runs a Jinja dialect (minijinja), so write filters, not Python
methods:
| Instead of |
Write |
text.split(",") |
text | split(",") |
d.get(k, 0) |
d[k] if k in d else 0 |
d.keys(), d.values() |
d | items | map(attribute=0), ... attribute=1 |
x | round(0, "ceil") |
math.ceil(x) |
"%d" % n |
n | format('d') |
Supported as in Jinja: set, for with loop.index0, if, macro,
namespace(), dict() with ** merging, range, string, int, float,
list, length, sort(attribute=...), map, selectattr, rejectattr,
groupby, unique, max, min, sum, join, replace, upper,
lower, round(n), abs, the ~ concatenation and // floor division.
Integers are 128-bit, not arbitrary precision. A runaway loop fails the chart
on an instruction budget, and output is capped by the project's
execution.max_template_output_bytes.
10. Verify
dct validate charts/flow.yml # header, channels, options, template syntax
dct render charts/flow.yml # the drawing, under the default theme
Render once more under a dark theme (theme: neon) to confirm nothing is
hard-coded. Check the four error codes if a render fails:
ERR-CUSTOM-TEMPLATE (file, header or syntax), ERR-CUSTOM-FIELDS
(channels or options against the header), ERR-CUSTOM-RENDER (the template
while drawing), ERR-CUSTOM-SVG (the output).
1---2name: custom-chart-build3kind: workflow4description: >5 Draw a chart shape no built-in type has with `type: custom`: an SVG template6 over the chart's query rows, rendered by the engine. Covers the authoring7 surface, the template header, every name the template sees (rows, style,8 variables, helpers), links, fonts, where the drawing lands, the allowed SVG,9 and the template dialect. Use when the user asks for a shape by name that no10 built-in type or composed recipe draws: a Sankey, funnel, gauge, radar, XmR11 chart, isotype pictogram, waffle. Do NOT use when a built-in type answers the12 question (see chart), or for styling an existing chart.13metadata:14 source: https://skillmd.com/skills/dbt-labs/custom-chart-build15 author: fivetran16---1718# Custom chart build1920A custom chart is a template that turns query rows into SVG. The engine21renders it, checks the output, and frames it like every other chart: the22title and subtitle above, the board's card padding around, the chart-root23`link:` honored. Reach for it last: a built-in chart gets axes, legends,24hover, sizing rules and visual warnings for free; a custom chart draws only25what its template draws.2627## 1. Check what the project already has2829```bash30dct describe templates/ # every template: description, channels, options31dct describe templates/funnel.svg.j232dct examples charts/custom-inline # a complete inline board to copy33```3435A `template:` name with no file lists the templates the project does have.3637## 2. Author the chart3839```yaml40queries:41 stages:42 columns: [stage, visitors]43 values:44 - [Visited, 4200]45 - [Signed up, 3100]46 - [Upgraded, 740]47charts:48 signup_flow:49 type: custom50 query: stages51 # template: funnel # templates/funnel.svg.j2, or the template inline52 svg: | # under svg: (exactly one of the two)53 {#---54 description: One bar per stage, each a link.55 channels:56 x: {}57 y: {}58 options:59 bar_height:60 type: integer61 default: 2462 ---#}63 {% set top = rows | map(attribute=channels.y) | max %}64 {% for r in rows %}65 <a href="{{ href(r) }}">66 <rect y="{{ loop.index0 * (options.bar_height + 8) }}" height="{{ options.bar_height }}"67 width="{{ r[channels.y] / top * width }}" fill="{{ style.fonts.secondary.color }}"/>68 </a>69 {% endfor %}70 title: Where visitors go71 x: stage # channels sit at the chart root, as on any chart72 y: visitors73 options:74 bar_height: 24 # the template's own settings75 link: /boards/stage/{{ x }} # optional: a click-through, like every chart76 style:77 aspect_ratio: 2 # sizing only: aspect_ratio, min_height, max_height78rows:79 - signup_flow80```8182Channels use the built-in names (`x`, `y`, `color`, `size`, `shape`, `theta`,83`value`); pick the role a built-in chart would use (a funnel's stage is `x`,84its count `y`; a waffle's parts are `color` and `theta`). Everything else the85template needs goes under `options:`. The look comes from the board's86`style:`, never from the chart.8788Let the query do the math. Sorting, ranking, shares, running totals and89binning belong in SQL; the template loops and draws, mapping data to pixels90with `d3` scales rather than inline arithmetic.9192## 3. Declare the header (template files)9394A template file opens with a YAML header in a Jinja comment. It is the95contract the chart's channels and options are validated against at compile:9697```jinja98{#---99description: Flow diagram from an edge list.100channels:101 x:102 description: Source node, then target node.103 multiple: true104 value:105 description: Size of each flow.106options:107 node_width:108 type: number109 default: 12110---#}111```112113No `default` means required; `default: null` means optional (`none` in the114template). Option types: `column`, `columns`, `string`, `number`, `integer`,115`boolean`, `color`. An inline `svg:` template takes the same header; without116one it declares no channels or options and reads columns by name (`r.revenue`).117118## 4. What the template sees119120| Name | Holds |121|---|---|122| `rows` | The query result, one mapping per row. A chart with no `query:` gets `[]`. |123| `columns` | The result's column names, in order. |124| `channels` | Declared channel to column: `channels.x` is a column name, a list for a `multiple` channel, `none` when optional and unset. |125| `options` | The chart's options with the header's defaults filled. |126| `width`, `height` | The drawing box in pixels: inside the card padding, below the title. Draw from `(0, 0)` to `(width, height)`. |127| `uid` | A prefix unique to this chart; use it for every `id` (`id="{{ uid }}-clip"`) so two charts on one board never collide. |128| `style` | The board's merged style tree, every color a hex value: `style.font.family`, `style.font.color`, `style.fonts.secondary.color`, `style.tones.positive`, `style.charts.color.categorical.palette`, `style.charts.axis.grid.color`, `style.palettes.<role>` (a list of colors, or a mapping of stops for a tone). |129| `variables` | The board's variable values for this render (`variables.region`). |130| `math` | `sin`, `cos`, `tan`, `asin`, `acos`, `atan2`, `sqrt`, `log`, `exp`, `floor`, `ceil`, `pi`, `tau`. Radians. Write a negative angle as `-1 * math.pi / 2`: `-math.pi` negates `math`. |131| `d3` | d3's scales, ticks, path generators, pie, stack and sankey layouts, symbols, `format`, color interpolators and schemes, geo projections and `geo_path`, in snake_case (below). |132133Helpers:134135| Helper | Returns |136|---|---|137| `value \| format('.1%')` | The value through a d3-format spec, the same specs `format:` takes elsewhere. |138| `value \| format(column=channels.y)` | The value through the format the board resolved for that column: the query's `formats:`, `style.formats`, the number locale and currency, the way a KPI prints it. Prefer it to a `value_format` option that only restates the column's format; keep an option only when the template should print something different. A spec and `column=` together is an error, as is a column the query did not return. Numbers only: a date or text value under `column=` is an error. With no rows there are no columns: wrap a derived total in `{% if rows %}`. |139| `text_width(text, size, weight)` | Pixel width of `text` in the board's font at `size`; `weight` optional (`600`, `"bold"`, or any weight `style` carries). Digits measure as tabular numerals, like the axis labels the engine draws. Measure labels instead of guessing. |140| `color_for(value, column)` | The board's pinned color for that column's value (`style.charts.category_colors`), else the next categorical palette color; stable within a chart. |141| `label_ink(color)` | `color` as text ink on the chart's background: the engine's dark step with a 4.5:1 floor, right on light and dark themes. |142| `variant(color, kind)` | `light`, `dark`, `pale` or `deep` tier of a hex `color`; the engine's palette-variant math. |143| `href(row)` | The chart's `link:` for that row, every `{{ channel }}` placeholder filled from the row. |144| `raise_error(message)` | Stops the render and shows `message` in the chart's place. Use it for data the template cannot draw. |145146`d3` replaces the arithmetic a template would repeat, and draws with the same147numbers the built-in charts use. Arguments go by position or keyword; a148zero-width domain, a non-numeric value or an unknown curve fails the chart149with an error naming the call.150151| `d3` function | Returns |152|---|---|153| `d3.scale_linear(domain, range)` | A scale for two-number lists. `x(v)` maps, `x.invert(px)` maps back, `x.domain` and `x.range` read the ends, `x.nice(count=10)` returns a new scale with round ends, `x.ticks(count=10)` the tick list, `x.tick_format(count=10, spec=none)` a function printing a value at the ticks' precision through the board's number locale (`spec` is a d3-format spec). |154| `d3.scale_sqrt(domain, range)` | The same, range proportional to the square root of the value: radius from a value so area follows it. |155| `d3.scale_log(domain, range, base=10)`, `d3.scale_pow(domain, range, exponent=1)`, `d3.scale_symlog(domain, range, constant=1)` | The same methods. A log domain must not cross or touch zero; `exponent` is not zero; `constant` is positive. A log scale's `tick_format` prints `""` for the ticks d3 thins from a crowded decade, and a value with no position (log of 0) is an error. |156| `d3.scale_band(domain, range, padding=0, padding_inner=0, padding_outer=0, align=0.5)` | Names to bands: `b(name)` is the band start, `b.bandwidth()` the width, `b.step()` the pitch; `padding=` sets both paddings. A name outside the domain is an error. |157| `d3.scale_point(domain, range, padding=0, align=0.5)` | Names to points: `p(name)` is the position (one point sits at the range's center), `p.step()` the pitch; `padding=` is the outer padding. A name outside the domain is an error. |158| `d3.line(points, curve="linear")`, `d3.area(points, y0, curve="linear")` | A path `d` through `[x, y]` pairs; `area` closes down to the line at `y0`. Curves: `linear`, `monotone_x`, `monotone_y`, `step`, `step_before`, `step_after`, `basis`, `natural`, `cardinal`. |159| `d3.arc(inner_radius, outer_radius, start_angle, end_angle, pad_angle=0, corner_radius=0)` | A sector path `d` centered on the origin; angles in radians clockwise from twelve o'clock; place it with `transform="translate(cx, cy)"`. |160| `d3.pie(values, start_angle=0, end_angle=math.tau, pad_angle=0)` | A list of `{index, value, start_angle, end_angle, pad_angle}` in data order (no default sort: order in the query), ready for `d3.arc`. |161| `d3.geo_mercator()`, `d3.geo_equal_earth()`, `d3.geo_orthographic()`, `d3.geo_albers_usa()`, `d3.geo_identity()`, … (every d3-geo projection, snake_case) | A projection: `p([lon, lat])` maps (none where the projection has no place for the point), `p.invert([x, y])` maps back. Settings are methods that read with no argument and return a new projection with one: `scale`, `translate`, `center`, `rotate`, `parallels`, `clip_angle`, `clip_extent`, `precision`, `angle`, `reflect_x`, `reflect_y`; `fit_size([w, h], geojson)` (also `fit_extent`, `fit_width`, `fit_height`) scales and translates to show the object in the box. |162| `d3.sankey(links, nodes=none, size=none, extent=none, node_width=24, node_padding=8, align="justify", iterations=6)` | d3-sankey's layout over `{source, target, value}` links (nodes named by string or number, in order of first appearance unless `nodes` lists them; `size=[w, h]` is the box). Returns `{nodes, links}`: nodes carry `name, index, value, depth, height, layer, x0, x1, y0, y1, source_links, target_links`; links `index, source, target` (the node mappings), `value, width, y0, y1`. A cycle is an error. |163| `d3.sankey_link_horizontal(link)` | The `d` of a link's centerline; stroke it with `stroke-width="{{ link.width }}"`, `fill="none"`. Printed the way the engine prints every chart's path (two decimals at most). |164| `d3.stack(series, order="none", offset="none")` | d3-shape's `stack()` over `series[i][j]` (lists of equal length; `none` for no datum). Returns `{series, index}`: `series[i][j]` is `[y0, y1]` (`none` for no datum) and `index[i]` the series' place in the order. `order`: `none`, `ascending`, `descending`, `inside_out`, `reverse`, `appearance`; `offset`: `none`, `expand`, `diverging`, `silhouette`, `wiggle`. |165| `d3.symbol(type="circle", size=64)` | d3-shape's symbol `d`, `size` square pixels, centered on the origin: `circle`, `cross`, `diamond`, `square`, `star`, `triangle`, `wye` to fill; `plus`, `times`, `triangle2`, `asterisk`, `square2`, `diamond2` to stroke. Printed the way the engine prints every chart's path (two decimals at most). |166| `d3.format(spec)` | The `format` filter as a function: `d3.format('$,.0f')(v)` prints through the board's number locale. |167| `d3.scale_utc(domain, range)` | `scaleUtc` for two instants (milliseconds or ISO-8601 text, a bare clock is UTC) and a two-number range. `x(t)` maps, `x.invert(px)` gives milliseconds, `x.domain` (ms) and `x.range` read the ends, `x.ticks(count=10)` the tick instants in ms, `x.nice(count=10)` a new scale with round ends, `x.tick_format(count=10, spec=none)` a function printing an instant in UTC through the board's time locale (d3's multi-scale format, or a d3-time-format `spec`). |168| `d3.time_format(spec)`, `d3.time_parse(spec)` | `utcFormat` and `utcParse` through the board's time locale: `d3.time_format('%b %d')(t)` prints an instant (ms or ISO text) in UTC, `d3.time_parse('%d.%m.%Y')(text)` gives ms or `none`. |169| `d3.interpolate_rgb(a, b)`, `d3.interpolate_hcl(a, b)` | A function of `t` in [0, 1] mixing two colors (hex, `rgb()`, `hsl()`, CSS name), printed as `rgb(r, g, b)`. |170| `d3.scheme_category10`, `scheme_accent`, `scheme_dark2`, `scheme_paired`, `scheme_pastel1`, `scheme_pastel2`, `scheme_set1`, `scheme_set2`, `scheme_set3` | d3-scale-chromatic's categorical schemes, lists of hex colors. Prefer `style.charts.color.categorical.palette` or `color_for` so colors follow the theme. |171| `d3.geo_path(projection=none, digits=3, point_radius=4.5)` | d3's `geoPath`: `path(geojson)` is the `d` of a GeoJSON mapping (`Feature`, `FeatureCollection`, a geometry, `{"type": "Sphere"}`) or its JSON text, or none when nothing is drawn (a point behind the globe); `path.area`, `.bounds`, `.centroid`, `.measure` take the same object. The projection clips: a graticule or a point on the far side simply ends. |172173Names are strict: a misspelled column, option or style key fails the chart174and names the template line. Output is escaped, so a label with `<` draws as175text.176177## 5. Links178179Set `link:` on the chart like any other chart:180181- A link with no `{{ channel }}` placeholder wraps the whole drawing in one182 anchor; the template draws nothing extra.183- A link with placeholders (`/boards/stage/{{ x }}`) is per row: the template184 wraps the marks it wants clickable in `<a href="{{ href(r) }}">...</a>`. A185 template that never calls `href` under such a link fails the chart.186 Board paths resolve against the host; `http`, `https` and `mailto` pass187 through; anything else is refused.188189## 6. Fonts and theme190191Read fonts and colors from `style` rather than writing them in:192`font-family="{{ style.font.family }}"` paints the board font, and an export193embeds that font file exactly as it does for built-in charts. A template194that reads only `style` follows every theme, dark ones included.195196## 7. Where the drawing lands197198The engine draws the title and subtitle, then places the template's output199in a group translated below them, inside the card's padding. `width` and200`height` are that box, so a template never allows for the title or padding201itself. Output outside that box is clipped. A template that wants the full202card height omits `title:`.203204## 8. What the output may contain205206Well-formed SVG from drawing elements only: shapes (`rect`, `circle`,207`ellipse`, `line`, `polyline`, `polygon`, `path`), text (`text`, `tspan`,208`textPath`), grouping (`g`, `defs`, `symbol`, `use`), paint209(`linearGradient`, `radialGradient`, `stop`, `pattern`, `clipPath`, `mask`,210`marker`), `title` and `desc` (a `<title>` inside a shape is a native browser tooltip, not the board's tooltip card),211and `a` with an `href` the link rules above accept.212213Refused, never stripped (`ERR-CUSTOM-SVG` names the construct): `script`,214`foreignObject`, `style`, `image`, `filter` (shadow and blur and raster images215stay unsupported: vector-only, sandboxed output), animation elements, `on*` attributes, the216board's own hooks (`role`, `aria-*`, `data-*`, classes starting with `role-`217or `dbt-`), a paint attribute that is not a color or `url(#id)`, an `href` or218`url()` that is not `#local` outside `<a>`, `javascript:`, CSS escapes and219loading functions, a null interpolated into an attribute, nesting past 64220levels, comments, processing instructions,221CDATA, DOCTYPE.222223## 9. The template dialect224225The engine runs a Jinja dialect (minijinja), so write filters, not Python226methods:227228| Instead of | Write |229|---|---|230| `text.split(",")` | `text \| split(",")` |231| `d.get(k, 0)` | `d[k] if k in d else 0` |232| `d.keys()`, `d.values()` | `d \| items \| map(attribute=0)`, `... attribute=1` |233| `x \| round(0, "ceil")` | `math.ceil(x)` |234| `"%d" % n` | `n \| format('d')` |235236Supported as in Jinja: `set`, `for` with `loop.index0`, `if`, `macro`,237`namespace()`, `dict()` with `**` merging, `range`, `string`, `int`, `float`,238`list`, `length`, `sort(attribute=...)`, `map`, `selectattr`, `rejectattr`,239`groupby`, `unique`, `max`, `min`, `sum`, `join`, `replace`, `upper`,240`lower`, `round(n)`, `abs`, the `~` concatenation and `//` floor division.241Integers are 128-bit, not arbitrary precision. A runaway loop fails the chart242on an instruction budget, and output is capped by the project's243`execution.max_template_output_bytes`.244245## 10. Verify246247```bash248dct validate charts/flow.yml # header, channels, options, template syntax249dct render charts/flow.yml # the drawing, under the default theme250```251252Render once more under a dark theme (`theme: neon`) to confirm nothing is253hard-coded. Check the four error codes if a render fails:254`ERR-CUSTOM-TEMPLATE` (file, header or syntax), `ERR-CUSTOM-FIELDS`255(channels or options against the header), `ERR-CUSTOM-RENDER` (the template256while drawing), `ERR-CUSTOM-SVG` (the output).