---
# DESIGN.md · tokenstoagents.ai
# The canonical design file. One answer for type, color, and concept.
# Values: tokens.json is the single source of truth for every value.
# This front matter carries the identity decisions; it does not duplicate the token set.
canonical-home: tokenstoagents.ai · github.com/digitalcotton/tokens-to-agents-public
copyright: (c) 2026 Ryan Payne
license: CC BY-NC-ND 4.0 · attribution required, no derivatives, no commercial use · full terms in LICENSE.md
status: canonical
supersedes:
  - docs/visual-framework.md
  - tokens-to-agents-handoff/ (all design decisions within)
source-of-truth:
  values: site/tokens.json
  compiled: tokens.css (generated by Style Dictionary, never hand-edited)
identity:
  mode: monochrome
  accent-color: none
  emphasis: inversion only
  radius: 2px, one token, applied everywhere
  layout-max: 82.5rem
type:
  human-voice:
    family: N27
    foundry: atipo
    weights:
      light: 300 (display only, above 40px, never body)
      regular: 400 (plus the regular italic for emphasis inside body copy)
      medium: 500
      bold: 600 700 (declared as a range, both map to Bold)
    body: size.200, 1.0625rem (17px), at leading.normal 1.7
    fallback: ui-sans-serif, system-ui, sans-serif
    license: licensed for tokenstoagents.ai and tokenstoagents.com, not redistributable, excluded from the public repo
    consumed-as: font token only (--font-family-sans), never a hardcoded family
  machine-voice:
    family: Basier Square Mono
    foundry: atipo
    weights:
      regular: 400 (the only cut shipped)
    usage: code, token names and values, file paths, and structured-data excerpts, at 0.9em against the surrounding sans
    synthesis: font-synthesis disabled on every mono surface, so a weight the family does not ship is never faked
    fallback: ui-monospace, monospace
    license: licensed for tokenstoagents.ai and tokenstoagents.com, not redistributable, excluded from the public repo
    consumed-as: font token only (--font-family-mono), never a hardcoded family
  wordmark:
    family: N27
    weight: 500 (medium)
    styling: lowercase, tokens then an arrow then agents, tight tracking, header and footer alike
palette:
  ramp: warm paper to cool ink, nine primitive grays
  paper: gray.050 "#F6F5F2"
  ink: gray.950 "#0B0B0D"
  tiers: primitive, semantic, component. Three only.
rules:
  - a component token never points at a raw primitive
  - deprecate, never rename
  - no raw hex, pixel, or font literals in markup or styles
  - no em dashes, no en dashes, anywhere, including code comments
  - honor prefers-reduced-motion with a static end state
  - contrast holds WCAG AA; gray.700 is the muted text color on paper, gray.400 is borders on paper and muted-inverse text on ink
---

# The design, in prose

This file pairs the machine-readable decisions above with the reasoning a human or an agent should hold while building. Read the front matter as law and this prose as intent. When the two ever disagree, the front matter and tokens.json win, and this file gets fixed.

## Monochrome on purpose

The site is true monochrome: a single grayscale ramp from a warm paper to a cool, blue-black ink, with no chromatic accent anywhere. This is an argument, not a style preference. Stripping color out forces structure, type, and motion to carry the design, so the discipline stays visible. Emphasis is inversion, never a second color: a block that needs weight flips from ink-on-paper to paper-on-ink. The only chroma in the system is the faint temperature difference between the warm paper and the cool ink, and that is deliberate. If a reviewer can name an accent color, something has drifted.

## Two voices, one answer each

The human voice is N27, licensed from atipo. It carries the argument: prose, headlines, annotations, labels, and UI chrome. Weights carry the hierarchy: Bold (700, with 600 declared into the same cut) for page titles and primary headings, Medium (500) for subheads, nav, labels, and chrome, Regular (400) for body copy at 17px with 1.7 leading, and Light (300) reserved for display sizes above 40px, never for body. The wordmark ("tokens", an arrow, "agents", all lowercase) is set in this voice at medium (500), in the header and the footer alike. The layer numbers and station labels on the signature belong to this voice as chrome; only the values they point at are machine content.

The machine voice is Basier Square Mono, licensed from atipo, shipped in Regular (400) only. It carries everything that is, or represents, structured data: code, token names and values, file paths, and structured-data excerpts, set at 0.9em against the surrounding sans. The two faces share the same cap height and x-height, so no size-adjust is needed; the 0.9em compensates for the mono's wide set. font-synthesis is off on every mono surface, so a weight the family does not ship is never faked. It is consumed only through the font.family.mono token, never as a hardcoded family, so a future swap propagates in one edit.

There are no candidates and no alternatives in this file on purpose. Earlier drafts listed options, three files disagreed, and an agent caught the conflict mid-build. This file is the fix. One canonical answer per decision, every earlier draft superseded.

Never blur the voices. Prose is never mono, code is never sans. The separation is the meaning: it mirrors how this whole system pairs human intent with machine-readable structure.

## The values live in one place

Every visual value on every page comes from a DTCG token in tokens.json, compiled through Style Dictionary into CSS custom properties, consumed only as var(--token-name). Three tiers: primitive, semantic, component. A component points at a semantic, a semantic points at a primitive, and a component never reaches past the semantic layer to a raw primitive, because that is the shortcut that makes dark mode a three-month job. Tokens get deprecated, never renamed, because a rename is a breaking change to every consumer.

This file does not restate the token set. Restating it would create a second copy, and a second copy is a drift waiting to happen. tokens.json is the source. The compiled tokens.css is output. This file is intent.

## One signature, quiet everywhere else

The site spends its entire boldness budget on the kinetic stack signature on the map, the one place where a value visibly travels the four stations. Every other screen is static or uses the smallest calm transition. The quiet is not timidity; it is the setting that lets one bold thing register. Any new motion proposal starts from no.

Layout is left-aligned and asymmetric on generous paper, never a centered hero. The grid is treated as real structure. Corners are sharp: one 2px radius token, applied everywhere, no exceptions, no pills, no soft cards.

## The floor that is not negotiable

Semantic HTML with a single h1 per page and a skip link. Visible keyboard focus on every interactive element. prefers-reduced-motion honored fully, with a static end state built alongside any animated one, not after it. Contrast holds AA: gray.700 is the muted text color on paper and clears AA at every size in use; gray.600 no longer carries text on paper; gray.400 is a border color on paper and carries text only as muted-inverse on ink. Copy is sentence case, uppercase only for mono eyebrows and labels, straight quotes, and no em or en dashes anywhere, including code comments. Box-drawing characters in ASCII trees are permitted; they are a different Unicode block and are not dashes.

## Licensing note for the public repo

N27 and Basier Square Mono are both licensed from atipo, covering tokenstoagents.ai and tokenstoagents.com. Neither license permits redistribution, so the font files are excluded from the public repository and the repo builds on the fallback stacks. That exclusion is care, not omission, and it is stated in the README so nobody mistakes it for a missing asset.

## How this file is governed

This is a layer 04 file: runtime context, the intent agents execute against. It changes by decision, not by accumulation. When a decision changes, this file is edited in the same commit as the tokens it governs, the date below moves, and whatever it supersedes stays superseded. If you are an agent reading this: build to the front matter, keep every value a token reference, and when you find a conflict between this file and anything else in the repo except tokens.json, this file wins and the conflict is a bug worth reporting.

Canonical as of 2026-07-03. Curated by Ryan Payne.

From the public canon of tokenstoagents.ai · (c) 2026 Ryan Payne · CC BY-NC-ND 4.0 · see LICENSE.md