tokens/scale.mjs

Functions

Imports

It imports tokens/palette.mjs. No module of this repo imports it.

Source

1// Every token that is not a colour: space, radius, type, control size, motion, layers,
2// focus, the reading context, and the two contexts' aliases. `node tokens/scale.mjs` writes
3// tokens/scale.css, tokens/themes.css and tokens/tokens.json; `--check` regenerates them in
4// memory and refuses any difference from the committed files.
5//
6// The values and their reasons are in capsomer/research/design.md, section 1.5, as approved
7// on 2026-09-30. Each is a default: change it here, run `npm run tokens`, and record why.
8//
9// Density (release 0.2): the sizes a person feels (control height, padding, text size, gap,
10// row height) come in two sets. Compact is the default and starts from the Capsid Portal's
11// values; comfortable starts from shadcn's vega spacing (36 px controls, 14 px text, px-3).
12// `[data-density="comfortable"]` on the root or on any wrapper changes them for its subtree.
13// Every density token is written as a literal in both blocks, never as a var() chain, so a
14// wrapper does not inherit a value already resolved at the root.
15import { readFileSync, writeFileSync } from "node:fs";
16import { fileURLToPath } from "node:url";
17import { ELEVATION_ORDER, FAMILIES, themes } from "./palette.mjs";
18
19const here = (p) => fileURLToPath(new URL(p, import.meta.url));
20
21// [name, value, what it is for]. Names are short on purpose (decision 2): an app renames
22// its own colliding tokens when it adopts.
23export const SCALE = {
24  space: [
25    ["space-1", "2px", "hairline gaps: an icon beside its count"],
26    ["space-2", "4px", "inside a control: icon to label"],
27    ["space-3", "8px", "between controls in a toolbar"],
28    ["space-4", "12px", "between rows of a form, cell padding"],
29    ["space-5", "16px", "panel padding, the page gutter on a phone"],
30    ["space-6", "24px", "between panels, the page gutter"],
31    ["space-7", "32px", "between sections"],
32    ["space-8", "48px", "between major regions of a reading page"],
33    ["space-9", "64px", "above a page footer"],
34  ],
35  radius: [
36    ["radius-s", "3px", "kbd, chips inside text"],
37    ["radius-m", "6px", "controls"],
38    ["radius-l", "10px", "panels and dialogs"],
39    ["radius-xl", "14px", "cards (shadcn's rounded-xl)"],
40    ["radius-full", "999px", "pills and switches"],
41  ],
42  type: [
43    ["fs-h3", "18px", "a panel or dialog title"],
44    ["fs-h2", "22px", "a page title in the app"],
45    ["fs-prose", "clamp(17px, 1rem + 0.25vw, 19px)", "body text in the reading context"],
46    ["fs-prose-h2", "clamp(22px, 1.2rem + 1.2vw, 30px)", "a heading in the reading context"],
47    ["fs-input-coarse", "16px", "a form input on a touch screen, so iOS does not zoom"],
48    ["prose", '"Source Serif 4", "Iowan Old Style", Charter, Georgia, serif', "long-form text and public headings (decision 5)"],
49    ["display", '"Schibsted Grotesk", "Segoe UI", "Helvetica Neue", Arial, sans-serif', "a heading that wants a display face (the page head's title, an app's own headings); Schibsted Grotesk at 800, the UI face's own heavy weight; a site may set its own"],
50  ],
51  motion: [
52    ["dur-fast", "100ms", "feedback (hover, press) and every exit: what leaves goes faster than it came"],
53    ["dur-base", "200ms", "an overlay or a page arriving"],
54    ["dur-slow", "400ms", "a spring settling (with --ease-spring); a page-level change"],
55    ["ease-out", "cubic-bezier(0.16, 1, 0.3, 1)", "things arriving and leaving: a fast start and a long soft stop (Radix Themes, Arc)"],
56    ["ease-in-out", "cubic-bezier(0.65, 0, 0.35, 1)", "things moving within the page"],
57    ["ease-spring", "linear(0, 0.005 1%, 0.028 2.5%, 0.117 5.5%, 0.572 16%, 0.77 21.5%, 0.839 24%, 0.906 27%, 0.956 30%, 0.992 33%, 1.012 35.5%, 1.026 38%, 1.035 41%, 1.038 44.5%, 1.035 49.5%, 1.012 63.5%, 1.003 72.5%, 0.999 84.5%, 1)", "a release or a thumb settling: a damped spring, 95% at 30% of the time, 4% past; transform only, with --dur-slow"],
58  ],
59  layer: [
60    ["z-base", "0", "the page"],
61    ["z-sticky", "20", "a sticky top bar or anchor bar"],
62    ["z-tabbar", "30", "the phone tab bar"],
63    ["z-overlay", "40", "a scrim and a side panel"],
64    ["z-message", "70", "the status region"],
65    ["z-tip", "80", "a tooltip"],
66  ],
67  focus: [
68    ["focus-width", "2px", "the focus outline, WCAG 2.4.13's 2 px perimeter; its colour is --ring, checked at 3:1 by palette.mjs"],
69    ["focus-offset", "2px", "space between the control and its ring"],
70    ["ring-width", "3px", "the soft glow around a focused field (shadcn's ring-3); the 2 px outline stays the focus indicator"],
71  ],
72  layout: [
73    ["measure", "66ch", "a reading line (Bringhurst's 66 characters)"],
74    ["rail-w", "208px", "the shell's left menu, expanded"],
75    ["rail-w-collapsed", "56px", "the shell's left menu, collapsed to icons"],
76    ["top-h", "44px", "the shell's top bar (the Portal's, #215)"],
77    ["header-h", "3.5rem", "the site header, 56px on every site and surface (docs/design/design-site-header.md, answer 6)"],
78  ],
79  // The hover touches a site may turn on in its SITES entry (tokens/sites.mjs); the defaults are off.
80  touch: [
81    ["link-rule", "0px", "the site header's section links: an underline that grows in under the pointer; 0 draws none"],
82    ["icon-radius", "6px", "the site header's icon controls and the theme button (--radius-m; 999px for a circle)"],
83    ["icon-border", "0px", "their outline's width, in the band's line"],
84    ["theme-turn", "0deg", "the theme button turns this far under the pointer"],
85    ["arrow-rest", "1", "a .cap-arrow's opacity at rest; 0 lets it slide in under the pointer"],
86    ["arrow-shift", "0px", "how far back a .cap-arrow sits at rest"],
87  ],
88};
89
90// Density: [name, compact, comfortable, what it is for]. `control` and `control-h` are the
91// same height (control-h is kept from 0.1). Touch raises control and target to 44 px in both.
92export const DENSITY = [
93  ["control", "32px", "36px", "a control's height with a fine pointer (the Portal's 32; shadcn vega's h-9)"],
94  ["control-h", "32px", "36px", "alias of --control, kept from 0.1"],
95  ["target", "24px", "28px", "the smallest hit area (WCAG 2.5.8 asks 24)"],
96  ["pad-x", "11px", "12px", "a control's inline padding (the Portal's 11; vega's px-3)"],
97  ["pad-y", "6px", "8px", "a control's block padding where it is not a fixed height (a textarea, a menu item)"],
98  ["pad-card", "16px", "24px", "a card or panel's padding (shadcn's card spacing, nova 16 and vega 24)"],
99  ["fs-label", "11px", "12px", "column labels and section titles, uppercase; nothing is set smaller"],
100  ["fs-detail", "12px", "13px", "the line under a row title"],
101  ["fs-body", "13px", "14px", "app body and rows (vega's text-sm)"],
102  ["fs-lead", "15px", "16px", "a page's lead line"],
103  ["gap", "12px", "16px", "between rows of a form and between sibling blocks"],
104  ["row-h", "36px", "44px", "the least height of a list or table row"],
105];
106const LEADING = ["leading", "1.45", "1.5"];
107// The alias components read for the reading size; it follows density.
108const TEXT_SIZE = ["text-size", "var(--fs-body)"];
109// Touch: the height a thumb needs wins over density.
110const COARSE = [["control", "var(--control-h-coarse)"], ["control-h", "var(--control-h-coarse)"], ["target", "44px"], ["row-h", "44px"]];
111
112// The reading context (design 1.4): one attribute on a region switches from dense app UI to
113// a reading page. It overrides density on the same element.
114export const PROSE = [
115  ["text-size", "var(--fs-prose)"],
116  ["leading", "1.6"],
117  ["gap", "var(--space-6)"],
118  ["control", "40px"],
119  ["face", "var(--prose)"],
120];
121
122const HEADER = (what) =>
123  `/* Generated by tokens/scale.mjs (${what}). Do not edit: change the script and run
124   \`npm run tokens\`. \`npm run check\` refuses a file that differs from what it writes. */\n`;
125
126export function renderScale() {
127  const lines = [];
128  for (const [group, rows] of Object.entries(SCALE)) {
129    lines.push(`  /* ${group} */`);
130    for (const [name, value] of rows) lines.push(`  --${name}: ${value};`);
131  }
132  const set = (col) => DENSITY.map(([n, c, k]) => `  --${n}: ${col === 0 ? c : k};`).join("\n");
133  const rest = (col) => `  --${TEXT_SIZE[0]}: ${TEXT_SIZE[1]};\n  --${LEADING[0]}: ${LEADING[col + 1]};`;
134  return `${HEADER("space, radius, type, density, motion, layers, focus, layout")}:root {
135${lines.join("\n")}
136  --control-h-coarse: 44px;
137  --face: var(--ui);
138}
139/* Density: compact is the default, on the root or on any element; comfortable on any element
140   changes its subtree. Literals in every block, so a wrapper never inherits a stale value. */
141:root,
142[data-density="compact"] {
143${set(0)}
144${rest(0)}
145}
146[data-density="comfortable"] {
147${set(1)}
148${rest(1)}
149}
150[data-context="prose"] {
151${PROSE.map(([n, v]) => `  --${n}: ${v};`).join("\n")}
152}
153@media (pointer: coarse) {
154  :root,
155  [data-density] {
156${COARSE.map(([n, v]) => `    --${n}: ${v};`).join("\n")}
157  }
158  [data-context="prose"] {
159    --control: var(--control-h-coarse);
160  }
161}
162`;
163}
164
165// The two themes pinned to an element, for the site's side-by-side specimens:
166// <div data-cap-theme="dark"> shows the dark theme whatever the page's theme is. They follow
167// the purple family, the default; a pinned element can also carry data-family.
168export function renderThemes() {
169  const t = themes(FAMILIES.purple);
170  const block = (name) =>
171    `[data-cap-theme="${name}"] {\n${[...t.order, ...ELEVATION_ORDER].map((k) => `  --${k}: ${t[name].tokens[k]};`).join("\n")}\n  color-scheme: ${name};\n  color: var(--text);\n  background: var(--ground);\n}`;
172  return `${HEADER(`both themes pinned to an element, from the seed ${t.seed}`)}${block("light")}\n${block("dark")}\n`;
173}
174
175// The same values in the Design Tokens Community Group format (2025.10), for tools that
176// read it. The CSS is the contract; nothing in Capsomer reads this file (decision 15).
177export function renderJson() {
178  const t = themes(FAMILIES.purple);
179  const out = { $description: "Capsomer tokens. Generated by tokens/scale.mjs; the CSS files are the contract. type and control show the compact density; density-compact and density-comfortable hold both sets." };
180  const typeOf = (group) => ({ space: "dimension", radius: "dimension", control: "dimension", "density-compact": "dimension", "density-comfortable": "dimension", motion: undefined, layer: "number", focus: undefined, layout: undefined, type: undefined })[group];
181  const groups = { ...SCALE };
182  const compact = DENSITY.map(([n, c, , why]) => [n, c, why]);
183  const fs = compact.filter(([n]) => n.startsWith("fs-"));
184  groups.type = [...fs, ...groups.type];
185  groups.control = [...compact.filter(([n]) => ["control", "control-h", "target"].includes(n)), ["control-h-coarse", "44px", "a control's height with a coarse pointer"]];
186  groups["density-compact"] = compact;
187  groups["density-comfortable"] = DENSITY.map(([n, , k, why]) => [n, k, why]);
188  for (const [group, rows] of Object.entries(groups)) {
189    out[group] = {};
190    for (const [name, value, why] of rows) {
191      const ty = name.startsWith("dur-") ? "duration" : value.startsWith("cubic-bezier(") ? "cubicBezier" : name.startsWith("fs-") && group.startsWith("density") ? "dimension" : typeOf(group);
192      let v = value;
193      if (ty === "dimension" && /^\d+px$/.test(value)) v = { value: Number(value.slice(0, -2)), unit: "px" };
194      else if (ty === "duration") v = { value: Number(value.slice(0, -2)), unit: "ms" };
195      else if (ty === "cubicBezier") v = value.match(/[\d.]+/g).map(Number);
196      else if (ty === "number") v = Number(value);
197      out[group][name] = { ...(ty ? { $type: ty } : {}), $value: v, $description: why };
198    }
199  }
200  for (const scheme of ["light", "dark"]) {
201    out[`colour-${scheme}`] = {};
202    for (const k of t.order) out[`colour-${scheme}`][k] = { $type: "color", $value: t[scheme].tokens[k] };
203  }
204  return JSON.stringify(out, null, 2) + "\n";
205}
206
207const FILES = [
208  ["scale.css", renderScale],
209  ["themes.css", renderThemes],
210  ["tokens.json", renderJson],
211];
212
213export function check() {
214  const problems = [];
215  for (const [file, make] of FILES) {
216    let committed = null;
217    try {
218      committed = readFileSync(here(`./${file}`), "utf8");
219    } catch {
220      problems.push(`tokens/${file} is missing; run npm run tokens`);
221      continue;
222    }
223    if (committed !== make()) problems.push(`tokens/${file} differs from what tokens/scale.mjs writes; run npm run tokens`);
224  }
225  return problems;
226}
227
228if (process.argv[1] && fileURLToPath(import.meta.url).replace(/\\/g, "/").toLowerCase() === process.argv[1].replace(/\\/g, "/").toLowerCase()) {
229  if (process.argv.includes("--check")) {
230    const problems = check();
231    if (problems.length) {
232      console.error(`scale: ${problems.length} problem(s)\n  ${problems.join("\n  ")}`);
233      process.exit(1);
234    }
235    console.log("scale: tokens/scale.css, themes.css and tokens.json match the script");
236  } else {
237    for (const [file, make] of FILES) writeFileSync(here(`./${file}`), make());
238    console.log("scale: wrote tokens/scale.css, tokens/themes.css and tokens/tokens.json");
239  }
240}