0005: Generated record covers

Context#

A photocard needs art on its front, and an archive of hundreds of records cannot have an illustration made for each. Stock images and generated pictures would weigh down the site, break the flat ink look and need an API or a licence. The art had to be free, instant, unique per record, stable across builds and recoloured by the same tokens as the rest of the page. Teams also need to tell their cards apart at a glance, and a few of them want a motif of their own.

Decision#

Inkan draws a cover for every record as an inline SVG at build time. The drawing is a pure function of the record’s id, so the same file always gets the same print, and of the project’s ink and motif, so a team’s cards look like a set. Every project is assigned an (ink, motif) pair that no other project has, for as long as pairs remain. The SVG carries ink roles rather than colours and is painted by CSS, which means a cover changes with the theme and with any --inkan-ink-* override.

Motifs are functions. Seventy-six are built in: seventeen abstract prints, ten for infrastructure, platform and security teams, ten for product teams, twelve for operations, data and hardware teams, twelve for business teams, seven for finance teams and eight for engineering, product and company functions. Each team motif carries keywords, so a project called security, frontend, dbre or legal gets a shield, a browser window, database discs or a pair of scales without any configuration. A plugin can add or replace a motif with defineMotif and the motifs key, and give it keywords of its own.

How to use it#

Pin an ink or a motif per project#

1
name: "Payments"
2
description: "Ledger, settlement and everything that moves money."
3
ink: m
4
motif: ticker
5
owners: [jules, noor]
6
order: 20

Both are optional. The ink is the project’s colour everywhere (dots, sidebar, avatar rings, card underline); the motif only affects the covers.

An ink outside the six letters fails the build in the _project.yml schema. A motif that nobody registered fails the build too, naming the file and the available motifs:

1
inkan: project "sre": unknown motif "ring", did you mean "rings"? (available: a11y, arcs, bank, bars, ...)

How pairs are assigned#

The allocation runs once per build over every project, including bare folders without a _project.yml. Six inks and seventy-six built-in motifs give 456 pairs; plugin motifs add six more each.

1. Projects that pin both ink and motif are settled first. Two projects pinning the same pair share it.
2. Projects that pin one field get the other chosen from the free pairs. A half pin avoids the motifs and inks another half pin still needs.
3. Projects that pin nothing are allocated in id order. Each project ranks all pairs: pairs whose motif matches a keyword in the project’s id or name come first, then the rest, and within each group a stable hash of the id decides. The project takes the first pair that is still free.

Only when every pair is taken do pairs repeat. The ranking is stable across machines, so a build gives the same covers everywhere. Adding an unpinned project does not change the style of any project that comes before it in id order; a project that sorts earlier can move the ones after it. Because pinned projects are reserved before unpinned ones, adding a pin to any _project.yml can change the pair of an unpinned project. Pin both fields on the teams whose look must never move.

How a motif is matched to a team#

Every team motif owns a list of keywords (tables below). When a project does not pin a motif, the allocation splits its id and its name from _project.yml into words and looks for a motif that owns one of them:

• Text is split at every character that is not a letter or a digit, and at the lowercase-to-uppercase step inside a word, then lowercased. payments-core gives payments core; SecurityTools gives security tools; ML Platform / v2 gives ml platform v2.
• A word matches a keyword exactly or with a trailing s on either side, so payment finds payments and orders finds order. There is no stemming beyond that: authentication does not find auth.
• Each built-in keyword belongs to exactly one motif, so a word never points at two built-in motifs. A project whose words hit several motifs (platform-security hits lattice and shield) ranks both equally and the hash of the id decides.
• A match wins only while that motif still has a free ink. Six teams whose names contain security get a shield in six inks; the seventh gets the next free pair.
• A pinned motif always wins over a keyword match. A project that pins only ink still prefers a matching motif for the field it leaves open.
• A project that matches nothing is allocated by the hash alone, as before.

Keywords are matched against the project id (the folder name) and the name, nothing else; a description that says “security” does not count.

The built-in motifs#

Seventeen abstract prints, used by every project that has no keyword match and available to pin:

Eight of these abstract prints also own keywords, so data, finance, media and growth teams and the classic infrastructure disciplines land on them:

Ten motifs for infrastructure, platform and security teams (app/src/lib/motifs-infra.ts):

Ten motifs for product teams (app/src/lib/motifs-product.ts):

Twelve motifs for operations, data and hardware teams (app/src/lib/motifs-ops.ts):

Twelve motifs for business teams (app/src/lib/motifs-business.ts):

Seven motifs for finance teams (app/src/lib/motifs-finance.ts):

Eight motifs for engineering, product and company functions (app/src/lib/motifs-work.ts):

The keywords are chosen so that the team names most companies use get a themed motif, and a test keeps it that way: about 130 names from Engineering, Platform and SRE through Payments, KYC and Treasury to Sales, Marketing, Legal and Workplace (app/src/lib/team-catalog.test.ts) must each get a matching motif, on their own and all together on one site. Camel case does not split after a single leading lowercase letter, so iOS and eCommerce stay one word while SecurityTools and dataAPI split.

The nine remaining abstract prints (waves, sunburst, bricks, orbit, contour, checker, crescent, dots, triangles) own no keywords.

Every motif takes two decisions per project (the side it leans to, the number of teeth or rays, the thickness of a line) and the rest per record, so a team’s set is recognisable while every card differs.

What varies per record#

A motif receives two seeded random generators. record is seeded by the record id (payments/adr/0003-stripe-as-primary-provider) and decides positions, sizes, rotations and the paper grain. project is seeded by the project id, so the choices drawn from it are the same on every cover of a team. The record id also picks the card stock:

Each ink has a fixed second ink for overprints (cyan with magenta, magenta with yellow, yellow with cyan, green with cyan, violet with magenta, orange with magenta), so the same two-plate misregistration appears across a team’s set.

A shared motif alone would make a team’s cards hard to tell apart in a grid, so the record id also frames the print. Every cover zooms into its own part of the motif (1.15 to 1.85 times) at its own angle (up to 18 degrees either way), and the paper and black stocks get one flat shape in the second ink laid over the print, a disc or a band in its own place. A team’s set keeps its ink and motif while neighbouring cards differ in composition and colour balance. Plugin motifs are framed the same way and need no changes.

Renaming a file changes its id and therefore its cover. Changing a record’s title or body does not.

Status treatments#

A record that no longer describes the current state has its print treated, as a sticker on an old release would be:

Accepted, implemented, proposed and in-review covers print in full ink. Custom statuses get no treatment unless they reuse one of these ids.

Where covers appear#

• On every photocard: the record index, the latest records on the landing page, team pages, the timeline and the flippable card in a record’s rail.
• As the banner of each team card on the landing page, using the project’s newest record (or the project id when the project has no records yet).

Covers are written into the HTML, so they cost no requests. A page with many cards carries the SVG markup of each; the record index therefore renders the first 120 cards and mounts the rest as you scroll.

Recolouring#

The SVG uses classes that cover.css maps to tokens: --inkan-ink-<ink>, --inkan-ink-k, --inkan-paper, --inkan-bg-2 in Stage and the blend mode --inkan-blend. Override those tokens in customCss and every cover follows; see Theme with —inkan-* CSS tokens. There is no per-record cover setting and no way to supply an image instead.

Add your own motif#

A motif is a module whose default export is a MotifFn, wrapped in defineMotif. A plugin registers it under a name with the motifs key, and any _project.yml can then pin that name. The second argument of defineMotif takes keywords, so projects whose id or name contains one of them get the motif without pinning it. This is examples/company-decisions/plugins/stamp.ts:

1
import { defineMotif } from '@tilaven/inkan';
2
import { circle, n, TAU } from '@tilaven/inkan/covers';
3

4
/** A rubber stamp: a ticked ring over a halftone cloud, with a black seal off to one side. */
5
export default defineMotif((c, record, project) => {
6
  const { w, h } = c;
7
  const side = project() < 0.5 ? 0.3 : 0.7;
8
  const teeth = 24 + Math.floor(project() * 3) * 8;
9
  const cx = w * (side + (record() - 0.5) * 0.12);
10
  const cy = h * (0.3 + record() * 0.12);
11
  const R = w * (0.26 + record() * 0.06);
12
  const tilt = (record() - 0.5) * 0.6;
13

14
  c.halftone({ spacing: 5, angle: 0.6, maxR: 2.6, cls: 'a', field: { cx, cy, r: w * 0.9, pow: 1.3, amp: 1.1 } });
15
  c.add(circle(cx, cy, R, ' class="b x"'));
16
  c.add(circle(cx, cy, R * 1.18, ` class="sa n x" stroke-width="${n(R * 0.14)}"`));
17
  let ticks = '';
18
  for (let i = 0; i < teeth; i++) {
19
    const a = tilt + (i / teeth) * TAU;
20
    const r0 = R * 1.3;
21
    const r1 = R * (i % 4 === 0 ? 1.55 : 1.42);
22
    ticks += `M${n(cx + Math.cos(a) * r0)} ${n(cy + Math.sin(a) * r0)}L${n(cx + Math.cos(a) * r1)} ${n(cy + Math.sin(a) * r1)}`;
23
  }
24
  c.add(`<path class="sk n" stroke-width="1.6" d="${ticks}"/>`);
25
  c.add(circle(cx, cy, R * 0.62, ' class="sk n" stroke-width="2.4"'));
26
  const seal = tilt + TAU * (0.6 + record() * 0.3);
27
  c.add(circle(cx + Math.cos(seal) * R * 1.9, cy + Math.sin(seal) * R * 1.9, w * 0.05, ' class="k"'));
28
}, { keywords: ['audit', 'controls', 'sox'] });

1
import { definePlugin } from '@tilaven/inkan';
2

3
export default definePlugin({
4
  name: 'acme',
5
  motifs: { stamp: new URL('./stamp.ts', import.meta.url) },
6
});

1
name: "Platform"
2
ink: y
3
motif: stamp

Rules for the motifs key:

• A name matches /^[a-z][a-z0-9-]*$/. Anything else fails config validation: plugins.0.motifs.Stamp: motif names use lowercase letters, digits and dashes and start with a letter.
• The value is an absolute path, a file: URL string or a URL. A URL with another scheme fails with plugin "acme" motif "stamp": expected a file path or file: URL, got ...; a file that does not exist fails with plugin "acme" motif "stamp": module not found: ....
• A later plugin wins over an earlier one, and a plugin motif named like a built-in replaces it for the whole site.
• The module’s default export must be a function, or the build fails with plugin motif "stamp" must default-export a function. An exception thrown while drawing fails with motif "stamp" failed for <record id>: ....

Rules for defineMotif(fn, options?):

• Without options it returns fn unchanged. With { keywords } it attaches the list to the function, which is what the registry reads.
• keywords must be an array of strings; anything else (a single string, numbers) throws inkan: defineMotif keywords must be an array of strings when the module loads.
• Each keyword goes through the same word splitting as project names: ['Legal', 'data-science'] becomes legal, data, science. Keep keywords to single lowercase words.
• A plugin keyword is not checked against the built-in lists. If stamp claimed legal, which scales owns, both would match and the hash would decide; audit, controls and sox are free today.
• A plugin motif that replaces a built-in name and sets keywords replaces that motif’s keyword list too. One that sets none keeps the built-in keywords of the name it replaces.

The motif is called with (canvas, record, project). record and project are the two generators described above; each call returns a number in [0, 1). Draw with ink classes instead of colours, so one print works in Day and Stage and on every stock:

The canvas is a MotifCanvas (types in lib/index.d.ts):

halftone takes HalftoneOptions: spacing between dots, the screen angle in radians, maxR (dot radius where the field is 1), cls (a, b, k or p), an optional clip id, and field, either one radial fall-off { cx, cy, r, pow, amp } or a list of linear ramps { x1, y1, x2, y2, amp? } that multiply.

@tilaven/inkan/covers exports four helpers for writing the markup: TAU (a full turn in radians), DEG (radians to degrees), n(v) (a number as an attribute value, one decimal, no -0) and circle(cx, cy, r, attrs?) (a <circle> element; attrs is raw attribute markup such as ' class="k"'). The built-in motifs in app/src/lib/motifs.ts, motifs-infra.ts and motifs-product.ts are written with the same API and are the best reference for more complex prints.

Consequences#

• Zero assets to make or store; a thousand records have a thousand distinct covers on the first build.
• Deterministic: the same repository builds the same covers anywhere, so screenshots and printouts stay consistent.
• Teams stay distinct until 222 pairs are in use (more with plugin motifs); after that, pairs repeat.
• Keyword matching depends on the folder name and name: renaming security to trust-and-safety keeps the shield (trust is a keyword), renaming it to blue-team loses it. Pin motif where the picture must survive a rename.
• Adding a pin or a project that sorts early can move the covers of unpinned projects. Pin both fields where the look matters.
• A plugin motif is code that runs at build time; a motif that throws stops the build. There is still no way to upload artwork per record.
• Renaming a record file gives it a new cover, which is a reason (next to broken links) to keep file names stable.
• Inline SVG on list pages adds to the HTML size; that is why the index streams cards in chunks.