@weatherboard/gyde-design 0.3.0

package/tokens.mjs

@@ -0,0 +1,398 @@
+/**
+ * G-48 — the token dictionary: its shape, its generator, and its guarantees.
+ *
+ * WHAT GYDE OWNS HERE, AND WHAT IT DOES NOT.
+ *
+ * Gyde owns the SHAPE — which categories exist, that roles are named for their
+ * purpose, that radius is closed, that a theme is complete, that the generated
+ * output is checked against its source. The product owns every VALUE. The seed
+ * dictionary below is a placeholder palette on purpose: it is replaced on day
+ * one and none of the guarantees care what it was replaced with (CHARTER §3).
+ *
+ * WHY THIS SHAPE.
+ *
+ * Both mature systems converged on it independently, which is the only reason
+ * to be opinionated about any of it:
+ *
+ * - **Radius closes to three semantic values.** System B and System A both
+ *   arrived at `card` / `control` / `pill`, separately, with the same names.
+ *   System A also measured that radius had NOT drifted — 2 distinct
+ *   values across 807 lines — while type and space had (8 and 15). So closing
+ *   radius costs nothing and should be first; type and space need budget.
+ * - **One shadow.** System A shipped with zero and a test asserting so,
+ *   precisely so that adding one had to be argued. The console cashed it in for
+ *   a dock floating over a live product, and the test now guards that there is
+ *   still exactly one.
+ * - **Roles, not appearances.** *"A token whose comment says 'grey' gets used
+ *   for the wrong grey… If you cannot write what a token is FOR, it is not a
+ *   token yet."* `describe()` enforces the readable half of this.
+ * - **Only colour is themed.** A 16px gap is 16px at night. Emitting space and
+ *   radius into both theme blocks doubles the file and creates two places for
+ *   one decision to drift.
+ *
+ * WHAT IS DELIBERATELY ABSENT: a z-index scale and motion tokens. System B has
+ * motion; System A deferred both rather than invent them ahead of need.
+ * A scaffolder that emits a category nobody uses has created drift, not
+ * structure — the unused parts are the parts that rot.
+ */
+
+/** A value that differs by theme. Only colour uses this. */
+export const themed = (light, dark) => ({ light, dark });
+const isThemed = (v) => v !== null && typeof v === "object" && "light" in v && "dark" in v;
+
+/**
+ * Words that describe how a value LOOKS rather than what it is FOR.
+ *
+ * A token called `grey` is a token that will be used for the wrong grey, and no
+ * rule downstream can recover from a dictionary whose names are appearances.
+ * Checked at generation time so the failure lands on whoever wrote the name.
+ */
+const APPEARANCE_WORDS = new Set([
+  "grey", "gray", "red", "blue", "green", "yellow", "orange", "purple", "pink",
+  "black", "white", "teal", "cyan", "dark", "light", "big", "small", "tiny",
+  "large", "huge", "bold", "thin", "round", "rounded", "square",
+]);
+
+/**
+ * The seed dictionary. Every value is a placeholder; every NAME is the contract.
+ *
+ * The role vocabulary is not invented here — it is System A's, and it
+ * earned its place by surviving a second application with a completely
+ * different palette mapping onto it exactly: an instrument panel's
+ * `live`, `attention`, `good`, `bad` and `unknown` landed on `accent`,
+ * `warning`, `success`, `danger` and `faint` with nothing left over.
+ */
+export const SEED = {
+  color: {
+    surface:  { value: themed("#ffffff", "#0b0d10"), role: "the page itself" },
+    raised:   { value: themed("#f7f8fa", "#12151a"), role: "a panel sitting above the page" },
+    inset:    { value: themed("#eef0f4", "#171b21"), role: "a well sunk into a panel" },
+    canvas:   { value: themed("#e9ebef", "#e9ebef"), role: "the area a drawing or map is rendered onto" },
+    text:     { value: themed("#14181f", "#dfe4ec"), role: "body copy and anything that must be read" },
+    muted:    { value: themed("#5b6472", "#7d879a"), role: "supporting text that is still information" },
+    faint:    { value: themed("#8b94a3", "#566072"), role: "present but not information — a placeholder, an absent value" },
+    border:   { value: themed("#d6dae1", "#242a33"), role: "the line between two surfaces" },
+    accent:   { value: themed("#1a6dff", "#4aa3ff"), role: "the one action this view wants" },
+    onAccent: { value: themed("#ffffff", "#0b0d10"), role: "text drawn on top of accent" },
+    success:  { value: themed("#1c7f52", "#46c08a"), role: "a thing that finished and was correct" },
+    warning:  { value: themed("#9a6b12", "#e0a63c"), role: "a thing that needs attention but has not failed" },
+    danger:   { value: themed("#b03a32", "#e56a63"), role: "a thing that failed, or an action that destroys" },
+  },
+  space: {
+    1: { value: "2px",  role: "the gap inside a control, against its own border" },
+    2: { value: "4px",  role: "between two things that are one thing" },
+    3: { value: "8px",  role: "between related items in a list" },
+    4: { value: "12px", role: "the default gap" },
+    5: { value: "16px", role: "padding inside a panel" },
+    6: { value: "24px", role: "between sections of a page" },
+    7: { value: "32px", role: "between a page's major regions" },
+    8: { value: "48px", role: "page margin at the top of a view" },
+  },
+  radius: {
+    card:    { value: "8px",   role: "anything that is a surface" },
+    control: { value: "6px",   role: "anything you can click or type into" },
+    pill:    { value: "999px", role: "a badge or a toggle, where the shape IS the affordance" },
+  },
+  text: {
+    micro:   { value: "11px", role: "metadata that is not read, only glanced at" },
+    small:   { value: "13px", role: "supporting text beside a control" },
+    body:    { value: "15px", role: "prose meant to be read" },
+    lead:    { value: "17px", role: "the first line of a section" },
+    title:   { value: "20px", role: "the name of a panel" },
+    display: { value: "28px", role: "the name of a page" },
+  },
+  weight:     { regular: { value: "400", role: "everything" }, medium: { value: "500", role: "a label against its value" }, strong: { value: "650", role: "a heading" } },
+  lineHeight: { body: { value: "1.5", role: "anything with more than one line" }, flush: { value: "1.1", role: "a heading, where the leading would read as a gap" } },
+  border:     { hair: { value: "1px", role: "the ordinary line between surfaces" }, marker: { value: "2px", role: "a line that means selected or active" } },
+  shadow:     { overlay: { value: themed("0 8px 24px rgb(16 20 26 / 0.14)", "0 8px 24px rgb(0 0 0 / 0.5)"), role: "a surface floating above content it does not belong to" } },
+  font:       { sans: { value: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif', role: "everything" }, mono: { value: 'ui-monospace, SFMono-Regular, Menlo, monospace', role: "anything the machine wrote" } },
+};
+
+/** `lineHeight` → `line-height`, `onAccent` → `on-accent`. */
+export const kebab = (s) => String(s).replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+
+/** The custom-property name for a token. This is the contract components read. */
+export const varName = (group, name) => `--${kebab(group)}-${kebab(name)}`;
+
+/**
+ * Structural checks on a dictionary, run before anything is generated.
+ *
+ * These are Gyde's guarantees, so they run against the PRODUCT's dictionary
+ * after it has replaced every value — not just against the seed.
+ */
+export function validate(dict) {
+  const problems = [];
+  const need = (cond, msg) => { if (!cond) problems.push(msg); };
+
+  need(dict.color, "no `color` group: a dictionary without colour roles is not a dictionary");
+  need(dict.radius, "no `radius` group");
+  need(dict.space, "no `space` group");
+  need(dict.text, "no `text` group");
+
+  // Closed sets. The point of a closed set is that widening it is a decision
+  // somebody makes on purpose, in a diff, with this message in front of them.
+  if (dict.radius) {
+    const keys = Object.keys(dict.radius).sort();
+    need(
+      JSON.stringify(keys) === JSON.stringify(["card", "control", "pill"]),
+      `radius must be exactly card/control/pill, got ${keys.join("/")} — ` +
+      "two independent systems closed to these three and neither has needed a fourth",
+    );
+  }
+  if (dict.shadow) {
+    need(
+      Object.keys(dict.shadow).length <= 1,
+      `shadow has ${Object.keys(dict.shadow).length} entries — depth is a semantic decision; ` +
+      "adding a second should be argued, not defaulted",
+    );
+  }
+
+  for (const [group, entries] of Object.entries(dict)) {
+    // `$`-prefixed keys are dictionary CONFIGURATION, not token groups. Without
+    // this the validator walked `$sameInBothThemes` — an array — and reported
+    // its elements as tokens with no value, so declaring a deliberate choice
+    // made the dictionary invalid. Config and content must not share a namespace
+    // without a marker, and this is the marker.
+    if (group.startsWith("$")) continue;
+    for (const [name, token] of Object.entries(entries)) {
+      const where = `${group}.${name}`;
+      if (!token || token.value === undefined) { problems.push(`${where}: no value`); continue; }
+      if (!token.role || String(token.role).trim().length < 8) {
+        problems.push(`${where}: no role. If you cannot write what a token is FOR, it is not a token yet`);
+        continue;
+      }
+      const words = String(token.role).toLowerCase().split(/[^a-z]+/);
+      const appearance = words.find((w) => APPEARANCE_WORDS.has(w));
+      if (appearance) {
+        problems.push(`${where}: role describes appearance ("${appearance}"), not purpose — ` +
+          "a token whose role says how it looks gets used for the wrong one");
+      }
+      // A themed value missing half a theme renders as nothing in that theme,
+      // silently. System A's dictionary test catches this and so does ours.
+      if (isThemed(token.value)) {
+        need(token.value.light && token.value.dark, `${where}: themed value is missing a theme`);
+      }
+    }
+  }
+
+  // A colour identical in both themes is usually a copy-paste, occasionally
+  // deliberate. Deliberate must be declared, so the accident cannot hide.
+  const deliberate = new Set(dict.$sameInBothThemes || ["canvas"]);
+  for (const [name, token] of Object.entries(dict.color || {})) {
+    if (isThemed(token.value) && token.value.light === token.value.dark && !deliberate.has(name)) {
+      problems.push(`color.${name}: identical in both themes — declare it in $sameInBothThemes if that is intended`);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * The header is deliberately NOT "generated by Gyde".
+ *
+ * This file lives in the product's repository and the product owns it, so it
+ * says what it is rather than who made it. The wording is also load-bearing:
+ * the emitted generator produces the same header, and the emitted test asserts
+ * the committed stylesheet equals what that generator produces. When the two
+ * headers differed, a freshly scaffolded repository shipped a token test that
+ * failed on its first run — the generated CSS and the generator disagreed about
+ * one line of comment.
+ */
+export const CSS_HEADER = `/* GENERATED — DO NOT EDIT.
+ *
+ * Edit the dictionary and regenerate. This file is committed so the CSS a
+ * reviewer approves is the CSS that ships, and a test asserts it still matches
+ * its source — a build-time generation step would mean the reviewed artifact
+ * and the shipped one are different files.
+ */`;
+
+/**
+ * Generate the stylesheet.
+ *
+ * `[data-theme]` is set on a CONTAINER, not only on `:root`. That is not a
+ * detail: it is what lets the catalogue render both themes side by side on one
+ * page, and what lets a portalled popup find the theme of the surface that
+ * opened it (`trigger.closest("[data-theme]")`) instead of rendering light on
+ * a dark panel — a real defect the deployed catalogue caught.
+ */
+export function generateCss(dict = SEED) {
+  const problems = validate(dict);
+  if (problems.length) {
+    throw new Error("Refusing to generate CSS from an invalid dictionary:\n  " + problems.join("\n  "));
+  }
+
+  const flat = [];
+  for (const [group, entries] of Object.entries(dict)) {
+    if (group.startsWith("$")) continue;
+    for (const [name, token] of Object.entries(entries)) {
+      flat.push({ name: varName(group, name), value: token.value });
+    }
+  }
+
+  const decls = (theme) => flat
+    .filter((t) => theme === "light" || isThemed(t.value))
+    .map((t) => `  ${t.name}: ${isThemed(t.value) ? t.value[theme] : t.value};`)
+    .join("\n");
+
+  return [
+    CSS_HEADER,
+    "",
+    ":root {",
+    "  color-scheme: light dark;",
+    decls("light"),
+    "}",
+    "",
+    "/* The system preference, unless a container has explicitly opted out. */",
+    '@media (prefers-color-scheme: dark) {',
+    '  :root:not([data-theme="light"]) {',
+    decls("dark").split("\n").map((l) => "  " + l).join("\n"),
+    "  }",
+    "}",
+    "",
+    "/* An explicit choice, on any element — which is what makes both themes",
+    "   renderable on one page, and what a portalled popup looks up. */",
+    '[data-theme="dark"] {',
+    decls("dark"),
+    "}",
+    "",
+    '[data-theme="light"] {',
+    decls("light"),
+    "}",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The plain-constant export.
+ *
+ * A decision learned rather than designed: **tokens have
+ * consumers that are not components.** An annotation SDK drawing an overlay
+ * inside somebody else's page cannot read our custom properties — they do not
+ * exist there — and anything plotting to a canvas needs the value, not the
+ * `var()`. System B ships plain constants beside its StyleX vars for exactly this.
+ *
+ * Generated from the same dictionary rather than maintained beside it. System B
+ * maintains both by hand, because `defineVars` cannot import, and its own
+ * comment concedes the two are kept in step "by hand until fixture tests
+ * enforce it". Generating both from one source is the whole reason not to
+ * require a compiler here.
+ */
+export function generateConstants(dict = SEED, { theme = "light" } = {}) {
+  const out = {};
+  for (const [group, entries] of Object.entries(dict)) {
+    if (group.startsWith("$")) continue;
+    out[group] = {};
+    for (const [name, token] of Object.entries(entries)) {
+      out[group][name] = isThemed(token.value) ? token.value[theme] : token.value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Emit the W3C Design Tokens (DTCG) form.
+ *
+ * The prior-art survey found the format reached a first stable release and is
+ * supported by Style Dictionary and Tokens Studio, so emitting it costs little
+ * and buys interoperability with tooling we are not going to write. It is an
+ * OUTPUT, not the source: the source stays a plain object because that is what
+ * carries the `role` prose the validator depends on.
+ *
+ * NOTE: the DTCG version and its adoption were reported by the survey and are
+ * not verified here. Confirm before treating this output as conformant.
+ */
+export function generateDtcg(dict = SEED, { theme = "light" } = {}) {
+  const TYPE = { color: "color", space: "dimension", radius: "dimension", text: "dimension", border: "dimension", shadow: "shadow", font: "fontFamily", weight: "fontWeight", lineHeight: "number" };
+  const out = {};
+  for (const [group, entries] of Object.entries(dict)) {
+    if (group.startsWith("$")) continue;
+    out[group] = { $type: TYPE[group] ?? "other" };
+    for (const [name, token] of Object.entries(entries)) {
+      out[group][name] = {
+        $value: isThemed(token.value) ? token.value[theme] : token.value,
+        $description: token.role,
+      };
+    }
+  }
+  return out;
+}
+
+/**
+ * Emit the StyleX form: `defineVars` per group, plus the dark theme.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS THE ARGUMENT FOR G-100.
+ *
+ * G-58 rejected mandating StyleX partly on a measured cost: `tokens.stylex.ts`
+ * cannot import `index.ts`, because `defineVars` must resolve statically
+ * without executing the module. A consumer therefore maintains the same token
+ * values by hand in two files, conceding in their own comment that they are
+ * kept in step "by hand until the fixture tests enforce it."
+ *
+ * That is a real defect and it was the strongest thing said against the
+ * mandate. It is also not a property of StyleX — it is a property of writing
+ * the StyleX file by hand. G-58 said so itself: "Gyde's generator emits CSS,
+ * plain constants and DTCG from one dictionary, which is the problem not
+ * existing rather than being solved."
+ *
+ * So this is the problem not existing. Both files come from the same
+ * dictionary, in the same run, and cannot disagree — there is no second copy of
+ * the values for anybody to keep in step, by hand or otherwise.
+ *
+ * The static constraint is respected rather than worked around: the emitted
+ * module is literal values and `defineVars` calls, importing nothing. Anything
+ * that needed a runtime lookup would reintroduce exactly the failure this
+ * removes.
+ *
+ * @gyde-emits-source-for-another-repo
+ */
+export function generateStyleX(dict = SEED) {
+  const problems = validate(dict);
+  if (problems.length) {
+    throw new Error("Refusing to generate StyleX vars from an invalid dictionary:\n  " + problems.join("\n  "));
+  }
+
+  const groups = Object.keys(dict).filter((g) => !g.startsWith("$"));
+  const L = [];
+
+  L.push("// GENERATED — DO NOT EDIT.");
+  L.push("//");
+  L.push("// Emitted from the same dictionary as the CSS, in the same run. There is no");
+  L.push("// second copy of these values to keep in step: editing this file by hand is");
+  L.push("// how the two-file drift this generator exists to remove comes back.");
+  L.push("//");
+  L.push("// Imports nothing on purpose. `defineVars` must resolve statically without");
+  L.push("// executing the module, so a value read from another module cannot appear here.");
+  L.push("");
+  L.push('import { defineVars, createTheme } from "@stylexjs/stylex";');
+  L.push("");
+
+  for (const group of groups) {
+    const entries = Object.entries(dict[group]);
+    L.push(`export const ${group} = defineVars({`);
+    for (const [name, token] of entries) {
+      const v = isThemed(token.value) ? token.value.light : token.value;
+      L.push(`  ${name}: ${JSON.stringify(String(v))},${token.role ? `  // ${token.role}` : ""}`);
+    }
+    L.push("});");
+    L.push("");
+  }
+
+  // Only groups that actually carry a dark value get a theme. Emitting an
+  // empty createTheme for `space` would be a file saying something it does not
+  // mean, and the next reader would look for the dark spacing scale.
+  const themedGroups = groups.filter((g) => Object.values(dict[g]).some((t) => isThemed(t.value)));
+  if (themedGroups.length) {
+    L.push("// The dark theme, applied by putting this class on a container.");
+    for (const group of themedGroups) {
+      L.push(`export const ${group}Dark = createTheme(${group}, {`);
+      for (const [name, token] of Object.entries(dict[group])) {
+        if (!isThemed(token.value)) continue;
+        L.push(`  ${name}: ${JSON.stringify(String(token.value.dark))},`);
+      }
+      L.push("});");
+      L.push("");
+    }
+  }
+
+  return L.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}