Skip to main content

04.13Design system

Paper-and-ink theme: Claude Code skill for design tokens

Claude Code skill for design tokens, built at AR Labs: one CSS tokens file, a starter page and a written visual language, so agents build pages in one look.

Engraved plate: an inkwell with a dip pen beside a sheet of paper, ink and accent swatches and a row of phase dots.An engraved glass inkwell with a dip pen standing in it, beside a sheet of paper carrying swatch chips for paper, ink and accent and a row of phase dots.AR LABS · INSTRUMENT CABINET · DRAWER 04CALL NO. 04.130123456789paperinkaccentABCDFIG. 13 · PAPER-AND-INK THEMEINKWELL& SWATCHESPARTSAOne file ofdesign tokensBPhase coloursthat say stateCA starter pageDA writtenvisual languageKEEPS ONE LOOK CONSISTENT
On this page
  1. How it works
  2. The judgement it encodes
  3. What exists today
  4. Example

The paper-and-ink theme skill is a Claude Code skill, built at AR Labs, that holds our current look as design tokens an agent can build from: cream paper, warm brown ink, one monospace typeface (JetBrains Mono), and a set of phase colours that say what state each thing is in. The look was first drawn by our task-map renderer, then copied by hand into the goal map and other pages, and the copies drifted apart. The skill makes one tokens file the single source of the theme, and gives an agent what it needs to build a new page or diagram in it: the tokens, a starter page, and a written account of what each colour and stroke means. It is for agents, and the people directing them, that build pages and diagrams in this look.

How it works

The skill holds four things: a CSS tokens file (design tokens are named variables such as --page or --c-working that hold every colour and the font stack, in light and dark); a reference describing the visual language; a minimal starter document; and a list of the older pages that still carry their own copy of the colours and how each differs.

FIG. 01
flowchart LR
  R["Read the visual language"] --> S["Copy the starter page"]
  S --> T["Place the tokens for the output type"]
  T --> C["Render light and dark, check"]

Building a page is four steps. Read the visual language first, because the phase colours are claims: an amber card says "being worked now" to anyone who has seen a task map. Start from the starter page and delete what is not used. Place the tokens according to the kind of output. Then render the page in both themes with a headless browser and look at each screenshot at full size.

The phase colours carry the same meaning in every page that uses them. Each phase has a solid colour for strokes and tags and a translucent tint for the fill behind that stroke, and the heavier the stroke, the more the item asks for attention:

Phase Colour Means Stroke
next violet, solid the next thing heaviest
working amber being worked now heavy
you green waiting on a person heavy
ready blue ready to start, or recently active medium
later violet, dashed later, still blocked, or parked light, dashed
done grey finished, idle or out of scope thinnest

Where the tokens go depends on the output:

  • A hosted page that may load no external stylesheet, such as a Claude Artifact, gets the tokens inline in a style element.
  • A served page or a page in a repository links the tokens file, and if a build script produces the page, the script copies the file in on every build.
  • A standalone SVG carries the tokens in its own style element, because it reads no outer stylesheet.
  • An SVG inline in an HTML page carries none, because it inherits the page's tokens and a second copy would override them.

The judgement it encodes

One source, referenced, never copied by hand. Colours in a page's own CSS are always references to the tokens, never literal values, so a change to the tokens file reaches the page. A copy made by a build is regenerated each time; a copy made by hand drifts, which is how the existing differences between pages began.

One typeface. Hierarchy comes from size, weight, letter case and tracking, never from a second font.

Meaning is documented with the colour. If a change alters what a colour or weight means, the visual-language reference changes in the same commit.

A visible theme switch on every page. A page that only follows the system setting changes theme by itself when the operating system switches by time of day, and the reader cannot hold it. The skill requires every HTML page in this look to carry an Auto, Light and Dark switch, remembered per viewer, that still works where browser storage is blocked. A standalone SVG has nowhere to put a switch and follows the system setting.

Check at phone width. A page is done when text reads clearly on every tint in both themes and nothing is cut off in a 375-pixel-wide window.

What exists today

The theme is used by our task maps, our goal map and some long-form report pages, and the SVG diagram skill shares its ink colours and orchid accent. The older pages still carry their own hand-copied colours; the skill lists each one and how it differs, and each is rewired to the tokens file as separate code work. The neo-brutalist AR Labs style used for C4 diagrams is a separate look, kept by the C4 skill.

Example

Illustrative example. A card in a page built on the tokens, using the "being worked now" phase by name rather than by value. The tokens file defines both a solid phase colour (--c-working) and a translucent tint (--ph-working), with separate values for light and dark:

.card[data-phase="working"] {
  background: var(--ph-working);
  border: 3px solid var(--c-working);
  color: var(--stroke);
  font-family: var(--mono);
}

The 3-pixel border is the stroke weight the visual language sets for a card being worked now; a finished card would take a 1-pixel light-ink border and the grey tint.