# Write a record

*nods · The package*

A record states who made a site and what it was made with. Every credit is drawn from one.

```js
import { assertValid } from '@nodsto/record';

export const record = {
  project: { title: 'Kiln', year: 2026, url: 'https://kiln.example' },
  statement: 'Designed and built by {creators}',
  creators: [
    {
      name: 'Marigold',
      url: 'https://marigold.example',
      kind: 'studio',
      role: 'design',
      degree: 'lead',
    },
    {
      name: 'Pocket Monday',
      url: 'https://pocketmonday.example',
      kind: 'studio',
      role: 'development',
    },
  ],
  materials: [
    {
      kind: 'palette',
      name: 'Five colours',
      swatches: ['#1f2a44', '#c8553d', '#e9dcc3', '#7a8f6a', '#f2b84b'],
    },
  ],
};

assertValid(record);
```

## Start with the project, a statement and the creators.

The statement is your wording and the client’s. It may use three slots, `{creators}`, `{year}` and `{title}`, or stay empty for names alone. Type a slot the record does not have into the statement above, such as `{studio}`, and the check says so.

Each creator is one entity with a name and a web address. A studio counts once, however many people work there. Its people go in `members`, which the record page prints and the footer leaves out.

## Choose each role from the sixteen.

A role has a label for lists and a verb for a line that reads as a sentence. Add a `degree` of `lead`, `equal` or `supporting` where two creators share a role.

| Role | In a list | On a line | What it covers |
|---|---|---|---|
| `design` | Design | Designed by | Visual and interaction design, layout, and the design system. |
| `art-direction` | Art direction | Art directed by | Direction of the visual language and of commissioned work. |
| `development` | Build | Built by | Implementation, architecture, and performance of the build. |
| `photography` | Photography | Photographed by | Original photography produced for the work. |
| `illustration` | Illustration | Illustrated by | Original illustration or image-making produced for the work. |
| `motion` | Motion | Animated by | Animation, motion design, and time-based sequences. |
| `film` | Film | Filmed by | Cinematography, editing, and moving image. |
| `sound` | Sound | Scored by | Music, sound design, and audio production. |
| `copy` | Copy | Written by | Copywriting, editorial, and the words as published. |
| `type-design` | Type | Lettered by | Bespoke typeface or lettering drawn for the work. |
| `strategy` | Strategy | Shaped by | Positioning, naming, and the brief the work answers. |
| `research` | Research | Researched by | User research, testing, and the evidence behind decisions. |
| `accessibility` | Accessibility | Audited by | Accessibility review, remediation, and assistive testing. |
| `production` | Production | Produced by | Scheduling, budget, and delivery of the work. |
| `content-production` | Content | Edited by | Content entry, migration, and editorial production. |
| `infrastructure` | Infrastructure | Hosted by | Hosting, pipelines, and the operational surface. |

## Add what else is true of the site.

Six more fields are optional. A footer draws the creators, and the record page draws everything.

contributors Everyone else who worked on the site. Listed on the record page and kept out of the footer.

materials What the site was made with, such as a typeface, a library, a host or a palette.

licences How the work itself is licensed, with a scope where the code and the writing differ.

awards Recognition, with who gave it and when. It reads as a claim until it links to the issuer.

certifications A conformance claim such as WCAG, with its assessor. One without an assessor is shown as self-declared.

measurements A figure such as a Core Web Vital, with the tool that produced it and the date it was taken.

## Check a record before you draw it.

`validate` returns every issue it finds. `assertValid` throws on the first error. An error means the credit must not be drawn. A warning means it draws and something is lost.

check.js

```
import { validate } from '@nodsto/record';

const { ok, issues } = validate({ ...record, statement: 'Made by {studio}' });
```

issues

```
[
  {
    "severity": "error",
    "code": "statement.slot.unknown",
    "path": "statement",
    "message": "Unknown slot {studio}. Known slots: {creators} {year} {title}."
  },
  {
    "severity": "warning",
    "code": "statement.noCreators",
    "path": "statement",
    "message": "The statement names nobody. Add {creators}, or leave it empty."
  }
]
```

## Write the record into the page source.

The same record is written as JSON-LD for search engines and as humans.txt. Put the JSON-LD in a `<script type="application/ld+json">` element.

build.js

```
import { toHumansTxt, toJsonLdString } from '@nodsto/record';

const jsonld = toJsonLdString(record, 2);
const humans = toHumansTxt(record);
```

jsonld

```
{
  "@context": "https://schema.org",
  "@type": "CreativeWork",
  "name": "Kiln",
  "url": "https://kiln.example",
  "datePublished": "2026",
  "author": [
    {
      "@type": "Organization",
      "name": "Marigold",
      "url": "https://marigold.example",
      "jobTitle": "Design"
    },
    {
      "@type": "Organization",
      "name": "Pocket Monday",
      "url": "https://pocketmonday.example",
      "jobTitle": "Build"
    }
  ],
  "material": [
    {
      "@type": "Thing",
      "name": "Five colours"
    }
  ]
}
```

humans.txt

```
/* TEAM */
  Design: Marigold
  Site: https://marigold.example

  Build: Pocket Monday
  Site: https://pocketmonday.example

/* SITE */
  Name: Kiln
  palette: Five colours
```

## Publish the record as a page.

`recordPage` returns a whole HTML document with no script. It lists the creators and contributors, then the materials, licences, awards, certifications and measurements the record has. It takes `canonical`, `siteName`, `theme` and `css`.

Terminal

```
npm install @nodsto/page
```

build.js

```
import { recordPage } from '@nodsto/page';

const page = recordPage(record, { canonical: 'https://kiln.example/credits' });
```

With a record in hand, [draw the credit](https://docs.nods.to/credit/).

---
https://docs.nods.to/record/ · nods 0.1.0 · MIT