@weatherboard/gyde-design 0.3.0

package/emit.mjs

@@ -0,0 +1,862 @@
+/**
+ * G-49 / G-60 — what the scaffolder writes.
+ *
+ * Every emitter here returns `{ path: contents }`. Nothing touches the disk:
+ * `plan` prints the paths, `init` writes them, and both call the same function.
+ * A scaffolder whose dry run and real run can diverge cannot be reviewed before
+ * it writes into somebody's repository, and this is the mechanism that stops
+ * them diverging rather than a promise that they will not.
+ *
+ * WHAT IS EMITTED, AND WHAT IS NOT.
+ *
+ * The values are placeholders and the product replaces every one (G-47). What
+ * Gyde is actually shipping is the *structure*: closure at the wrapper boundary,
+ * a theming mechanism that cannot become an escape hatch, a defaults module that
+ * survives the RSC boundary, and a test that proves the first of those by
+ * reading the emitted source as text.
+ *
+ * THE SEED SET IS SMALL ON PURPOSE.
+ *
+ * One project derived a set from the 72 selectors an app actually rendered and found
+ * *"roughly nine components cover all seventy-two."* The sharper
+ * lesson: System A wrote a `Disclosure`, then **deleted it before
+ * merging** because its only call sites were outside the set — *"exactly the
+ * speculation that principle forbids."* A team that deletes a finished component rather
+ * than ship it unused is the standard this emitter has to meet, so System B's
+ * fourteen Base-UI-backed components are a **menu**, not a delivery. Five are
+ * emitted by default because five is what every product provably has; the rest
+ * arrive when a declared surface needs them.
+ *
+ * @gyde-emits-source-for-another-repo
+ *
+ * The string literals below are source for a SCAFFOLDED project, not for this
+ * one. `packages/review/paths.test.mjs` reads that marker and skips this file:
+ * without it, the guard resolves the emitted `./dictionary.mjs` against this
+ * directory and reports six broken imports in a file that has none.
+ */
+
+import { generateCss, SEED, varName, CSS_HEADER } from "./tokens.mjs";
+
+/**
+ * The version of what this emits.
+ *
+ * Bumped whenever a template changes, because it is the label a scaffolded
+ * repository records in its provenance manifest and the thing an upgrade
+ * reports moving between. It is the TEMPLATES' version, not the tool's: a fix
+ * to the scanner does not change what a customer's files should contain.
+ */
+/**
+ * The TEMPLATE version, which is not the package version and must not chase it.
+ *
+ * install.md has always said these move independently. G-101 gave that a hard
+ * consequence: the template version is what decides which rules BLOCK, so
+ * raising it to the enforcement threshold before the templates satisfy the
+ * mandates makes `init` scaffold a repository that fails its own gate on the
+ * first run. That is not a hypothetical — bumping this to 0.3.0 alongside the
+ * package did exactly that, because the emitted components style through CSS
+ * custom properties and G-100 mandates StyleX.
+ *
+ * So this stays below the threshold until the templates earn it. The rule, and
+ * `emit.test.mjs` enforces it: a fresh scaffold must pass the gate Gyde would
+ * run against it.
+ */
+export const SCAFFOLD_VERSION = "0.2.4";
+
+const GENERATED = (what) => `/* GENERATED BY GYDE — then yours.
+ *
+ * Gyde wrote this file once and will never overwrite it. Edit it freely: the
+ * values here are placeholders and replacing them is the point (CHARTER §3).
+ *
+ * What Gyde keeps checking is the ${what}. That is enforced continuously, not
+ * asserted at emission, because these components are expected to be edited —
+ * closure has to survive the editing or it was never a property of the system,
+ * only of its first commit.
+ */`;
+
+/* ------------------------------------------------------------------ tokens */
+
+export function emitTokens(dict = SEED, { path = "packages/design-tokens", tokensPackage = "@scaffold/design-tokens" } = {}) {
+  const dictSource =
+`${GENERATED("dictionary's shape: roles not appearances, radius closed to three, both themes complete")}
+
+/**
+ * Every token names what it is FOR, never what it looks like.
+ *
+ * "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." Gyde's validator rejects a
+ * role written as an appearance, so this is checked rather than hoped for.
+ */
+export const themed = (light, dark) => ({ light, dark });
+
+export const tokens = ${JSON.stringify(dict, null, 2)
+    .replace(/"value": \{\s*"light": ("[^"]*"),\s*"dark": ("[^"]*")\s*\}/g, '"value": themed($1, $2)')};
+
+export default tokens;
+`;
+
+  /**
+   * The generator, emitted into the product's repository.
+   *
+   * NOT imported from Gyde. integration.md §1 says `gyde.config.json` and the
+   * workflow file are the entire non-generated footprint, and an emitted test
+   * that imports the scaffolder at runtime would make every scaffolded project
+   * take a permanent dependency on the tool that scaffolded it — which is the
+   * lock-in this product is supposed to be the opposite of.
+   *
+   * So the product owns its generator, as the reference implementation does.
+   * Gyde's own `emit.test.mjs` asserts this emitted generator produces byte-
+   * identical CSS to Gyde's — two independent implementations pinned to each
+   * other, rather than one shared through a dependency.
+   */
+  const generatorSource =
+`${GENERATED("agreement between this file and the committed tokens.css")}
+
+const isThemed = (v) => v !== null && typeof v === "object" && "light" in v && "dark" in v;
+
+export const kebab = (s) => String(s).replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+export const varName = (group, name) => \`--\${kebab(group)}-\${kebab(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 guarantees. These hold whatever values you replace the placeholders with. */
+export function validate(dict) {
+  const problems = [];
+  if (!dict.color) problems.push("no \`color\` group");
+  if (!dict.radius) problems.push("no \`radius\` group");
+
+  if (dict.radius) {
+    const keys = Object.keys(dict.radius).sort();
+    if (JSON.stringify(keys) !== JSON.stringify(["card", "control", "pill"])) {
+      problems.push(\`radius must be exactly card/control/pill, got \${keys.join("/")}\`);
+    }
+  }
+  if (dict.shadow && Object.keys(dict.shadow).length > 1) {
+    problems.push("depth is a semantic decision; a second shadow should be argued, not defaulted");
+  }
+
+  for (const [group, entries] of Object.entries(dict)) {
+    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 bad = String(token.role).toLowerCase().split(/[^a-z]+/).find((w) => APPEARANCE_WORDS.has(w));
+      if (bad) problems.push(\`\${where}: role describes appearance ("\${bad}"), not purpose\`);
+      if (isThemed(token.value) && !(token.value.light && token.value.dark)) {
+        problems.push(\`\${where}: themed value is missing a theme\`);
+      }
+    }
+  }
+
+  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 intended\`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * The header, interpolated from Gyde's rather than restated.
+ *
+ * These two strings must be byte-identical: Gyde writes tokens.css and the
+ * test below asserts this generator reproduces it. When they differed by one
+ * line of comment, a freshly scaffolded repository shipped a token test that
+ * failed on its first run — and the first thing anyone does with a failing
+ * generated test is delete it.
+ */
+const HEADER = ${JSON.stringify(CSS_HEADER)}
+
+export function generateCss(dict) {
+  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 [
+    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");
+}
+`;
+
+  const testSource =
+`${GENERATED("source==output guarantee this file asserts")}
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { validate, generateCss } from "./generate.mjs";
+import { tokens } from "./dictionary.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+test("the dictionary holds its shape", () => {
+  assert.deepEqual(validate(tokens), []);
+});
+
+/**
+ * The source==output guarantee.
+ *
+ * The stylesheet is committed rather than built, so the CSS a reviewer approves
+ * is the CSS that ships. This test is what stops it rotting — without it, a
+ * generated file that nobody regenerates is just a stale file with a confident
+ * header.
+ */
+test("the committed stylesheet still matches the dictionary", () => {
+  const committed = readFileSync(join(HERE, "tokens.css"), "utf8");
+  assert.equal(committed, generateCss(tokens),
+    "tokens.css is stale or was hand-edited — regenerate it, do not edit it");
+});
+`;
+
+  /**
+   * The package manifest.
+   *
+   * Without one, pnpm cannot resolve `@acme/design-tokens` and the emitted
+   * imports — which now correctly name the workspace's own scope — still
+   * resolve to nothing. Emitting the specifier and not the package it points at
+   * is half a fix.
+   *
+   * No build step and no dependencies: the dictionary is plain ESM and the
+   * generator uses nothing but the language.
+   */
+  const manifest = JSON.stringify({
+    name: tokensPackage,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    exports: {
+      ".": "./dictionary.mjs",
+      "./dictionary.mjs": "./dictionary.mjs",
+      "./generate.mjs": "./generate.mjs",
+      "./tokens.css": "./tokens.css",
+    },
+    scripts: {
+      tokens: "node -e \"import('./generate.mjs').then(async g=>{const{tokens}=await import('./dictionary.mjs');const{writeFileSync}=await import('node:fs');writeFileSync('tokens.css',g.generateCss(tokens))})\"",
+      test: "node --test tokens.test.mjs",
+    },
+  }, null, 2) + "\n";
+
+  return {
+    [`${path}/package.json`]: manifest,
+    [`${path}/dictionary.mjs`]: dictSource,
+    [`${path}/generate.mjs`]: generatorSource,
+    [`${path}/tokens.css`]: generateCss(dict),
+    [`${path}/tokens.test.mjs`]: testSource,
+  };
+}
+
+/* ------------------------------------------------------- structural modules */
+
+/**
+ * The theming module (G-60 §1).
+ *
+ * This is the capability whose ABSENCE cost System B 754 lines of parallel
+ * primitives and 0% adoption in two apps — *"never a rule anyone broke; a
+ * capability the system did not have."* It ships on day one for that reason.
+ */
+function themeModule(dict) {
+  const slots = Object.keys(dict.color);
+  return `${GENERATED("guarantee that this cannot be used to restyle a component from outside")}
+
+/**
+ * Runtime theming, for colours that cannot be known when the CSS is written.
+ *
+ * A per-tenant brand is resolved per request, so it cannot be a build-time
+ * token. Without a first-class answer, products grow a parallel set of
+ * hand-styled primitives beside the design system and adoption goes to zero —
+ * that is measured, not hypothetical.
+ *
+ * HOW. A theme is plain CSS custom properties. The producer spreads
+ * \`themeVars(theme)\` onto an element **it already owns**; components beneath it
+ * that opt in with \`tone="themed"\` read them through \`var()\`. Inheritance is the
+ * connection, so there is no context and no provider.
+ *
+ * WHY NOT A PROVIDER. A provider has to render an element to carry the
+ * properties, which puts a box in the layout the caller did not ask for and
+ * cannot style — and this system deliberately has no \`className\` for them to
+ * fix it with.
+ *
+ * WHY THIS IS NOT A HOLE IN THE NO-CLASSNAME RULE. \`themeVars\` returns custom
+ * properties **only** — never \`backgroundColor\`, never a layout property — so it
+ * cannot restyle a component from outside. \`theme.test.ts\` asserts exactly that,
+ * and that test is the reason this is safe to expose.
+ */
+
+export type ThemeSlot = ${slots.map((s) => JSON.stringify(s)).join(" | ")};
+
+export type SurfaceTheme = Partial<Record<ThemeSlot, string>>;
+
+const SLOTS: readonly ThemeSlot[] = [${slots.map((s) => JSON.stringify(s)).join(", ")}];
+
+/** The custom property a slot is published as. Stable and human-readable, so it can be read in devtools. */
+export const themeVar = (slot: ThemeSlot): string => \`${"--theme-${slot}"}\`;
+
+export function themeVars(theme: SurfaceTheme): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const slot of SLOTS) {
+    const value = theme[slot];
+    if (value !== undefined) out[themeVar(slot)] = value;
+  }
+  return out;
+}
+`;
+}
+
+const themeTest = `${GENERATED("assertion below, which is what makes runtime theming safe to expose")}
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { themeVars, themeVar } from "./theme.js";
+
+/**
+ * The assertion that makes runtime theming safe to expose.
+ *
+ * If \`themeVars\` could ever return a real CSS property, it would be a
+ * \`style\` prop by another name and every refusal in this package would become
+ * advisory. So: custom properties only, checked.
+ */
+test("themeVars returns custom properties and nothing else", () => {
+  const out = themeVars({ surface: "#123456", accent: "#abcdef" } as never);
+  for (const key of Object.keys(out)) {
+    assert.ok(key.startsWith("--"), \`\${key} is not a custom property\`);
+  }
+});
+
+test("an unknown slot is dropped rather than passed through", () => {
+  const out = themeVars({ backgroundColor: "red", surface: "#fff" } as never);
+  assert.deepEqual(Object.keys(out), [themeVar("surface")]);
+});
+`;
+
+/**
+ * The defaults module (G-60 §2).
+ *
+ * The comment is long because the failure is invisible and the fix looks
+ * arbitrary. Somebody will eventually move these next to their components,
+ * which is the natural thing to do, and this is the only thing that will stop
+ * them.
+ */
+const defaultsModule = `${GENERATED("absence of a \"use client\" directive in this file")}
+
+/**
+ * Every component's defaults, spread at the call site.
+ *
+ * !! DO NOT ADD "use client" TO THIS FILE, AND DO NOT MOVE THESE BESIDE THEIR
+ * !! COMPONENTS.
+ *
+ * Most components in this package are "use client". A server component that
+ * imports a VALUE across that boundary does not get the value — it gets an
+ * opaque client reference with no enumerable properties. Spreading one yields
+ * {} and every prop silently reverts to undefined.
+ *
+ * That is not theoretical. \`<Card {...CARD_DEFAULTS}>\` on a server page rendered
+ * with every prop undefined, and React reported only "Element type is invalid …
+ * got: undefined" — naming neither the element nor the prop.
+ *
+ * This module carries no directive and imports nothing but types, so it stays in
+ * both graphs and its values survive on the server.
+ */
+
+export const BUTTON_DEFAULTS = { tone: "neutral", emphasis: "filled", size: "md" } as const;
+export const TEXT_DEFAULTS = { role: "body" } as const;
+export const CARD_DEFAULTS = { tone: "default", inset: "md" } as const;
+export const CHECKBOX_DEFAULTS = { disabled: false, indeterminate: false } as const;
+export const SELECT_DEFAULTS = { disabled: false } as const;
+`;
+
+/* -------------------------------------------------------------- components */
+
+/**
+ * The seed components.
+ *
+ * Five, and each one is here to carry a pattern the rest of the set will copy:
+ * a variant matrix, a component with no primitive beneath it, a surface, a
+ * simple primitive wrap, and a portalled primitive.
+ */
+export const SEED_COMPONENTS = ["Button", "Text", "Card", "Checkbox", "Select"];
+
+function componentSources(primitive) {
+  return {
+    "Button.tsx": `"use client";
+${GENERATED("closed prop surface — no className, no style, no render prop")}
+import { Button as Base } from "${primitive}/button";
+import type { ReactNode } from "react";
+
+/**
+ * TONE AND EMPHASIS, NOT A COLOUR.
+ *
+ * The variants are a matrix — three tones by three emphases — rather than nine
+ * independent style blocks. The rule that keeps it a system: **a new variant
+ * cannot introduce a colour.** It can only pick a tone and an emphasis. That is
+ * what makes "variants only where a real choice exists" checkable instead of a
+ * slogan.
+ */
+export type ButtonTone = "neutral" | "accent" | "danger" | "themed";
+export type ButtonEmphasis = "filled" | "outline" | "ghost";
+export type ButtonSize = "sm" | "md" | "lg";
+
+export type ButtonProps = {
+  children: ReactNode;
+  tone: ButtonTone;
+  emphasis: ButtonEmphasis;
+  size: ButtonSize;
+  /**
+   * Required and nullable rather than optional. An omittable onClick on a real
+   * button compiles, renders, and does nothing — pass null to say the no-op is
+   * deliberate.
+   */
+  onClick: (() => void) | null;
+  type?: "button" | "submit";
+  disabled?: boolean;
+  /** A disabled control with no explanation is the most common accessibility defect there is. */
+  describedBy?: string;
+};
+
+export function Button({ children, tone, emphasis, size, onClick, type = "button", disabled = false, describedBy }: ButtonProps) {
+  return (
+    <Base
+      // focusableWhenDisabled: a disabled button that leaves the tab order is a
+      // control a keyboard user cannot discover the existence of.
+      focusableWhenDisabled
+      type={type}
+      disabled={disabled}
+      aria-describedby={describedBy}
+      onClick={onClick ?? undefined}
+      data-ds="button"
+      data-tone={tone}
+      data-emphasis={emphasis}
+      data-size={size}
+    >
+      {children}
+    </Base>
+  );
+}
+`,
+
+    "Text.tsx": `${GENERATED("closed prop surface")}
+import type { ReactNode } from "react";
+
+/**
+ * No primitive beneath this one: text has no behaviour to adopt.
+ *
+ * \`role\` and \`as\` are separate axes on purpose. A heading that must be an <h2>
+ * for the document outline should not be forced to LOOK like one, and the
+ * alternative — one prop meaning both — is how type scales drift.
+ *
+ * \`as\` is three values, not a general element passthrough. Each was needed.
+ */
+export type TextRole = "micro" | "small" | "body" | "lead" | "title" | "display" | "muted" | "faint";
+
+export type TextProps = {
+  children: ReactNode;
+  role: TextRole;
+  as?: "p" | "span" | "code";
+};
+
+const DEFAULT_ELEMENT: Record<TextRole, "p" | "span"> = {
+  micro: "span", small: "span", body: "p", lead: "p",
+  title: "p", display: "p", muted: "span", faint: "span",
+};
+
+export function Text({ children, role, as }: TextProps) {
+  const Tag = as ?? DEFAULT_ELEMENT[role];
+  return <Tag data-ds="text" data-role={role}>{children}</Tag>;
+}
+`,
+
+    "Card.tsx": `${GENERATED("refusal to accept a radius, a colour, a shadow or a spacing override")}
+import type { ReactNode } from "react";
+
+/**
+ * The bordered box.
+ *
+ * It takes no radius prop and no shadow prop, and that is the entire point: one
+ * radius is what stops a repository growing seven. A caller who needs a
+ * different corner has found a gap in the set, which is a finding to file — not
+ * a licence to write bespoke CSS.
+ *
+ * \`tone="themed"\` reads the runtime theme (see theme.ts) rather than the
+ * dictionary, which is how a per-tenant brand works without an escape hatch.
+ *
+ * WHY THE SPACING PROP IS CALLED \`inset\` AND NOT \`padding\`.
+ *
+ * The two mature systems this was learned from disagree here. One takes a
+ * \`padding\` prop with a closed set of steps; the other forbids the key outright,
+ * alongside className and style. Both are defending the same rule — no component
+ * accepts a spacing OVERRIDE — and a closed set of four semantic steps is not an
+ * override, it is a variant.
+ *
+ * The stricter convention wins, on the narrow ground that a prop named after a
+ * CSS property is the one somebody eventually widens to take a raw value,
+ * because the name already implies it can. \`inset\` names the intent and cannot
+ * be read as an invitation.
+ *
+ * The sharper rule this stands in for — a prop is closed if its TYPE is a union
+ * of semantic names, whatever it is called — needs a type-aware check rather
+ * than a textual one, and is not built.
+ */
+export type CardTone = "default" | "muted" | "themed" | "success" | "warning" | "danger";
+export type CardInset = "none" | "sm" | "md" | "lg";
+
+export type CardProps = {
+  children: ReactNode;
+  tone: CardTone;
+  inset: CardInset;
+  as?: "div" | "section" | "article" | "li";
+};
+
+export function Card({ children, tone, inset, as: Tag = "div" }: CardProps) {
+  return <Tag data-ds="card" data-tone={tone} data-inset={inset}>{children}</Tag>;
+}
+`,
+
+    "Checkbox.tsx": `"use client";
+${GENERATED("closed prop surface across the wrapper boundary")}
+import { Checkbox as Base } from "${primitive}/checkbox";
+
+/**
+ * The primitive supplies BEHAVIOUR only — focus, keyboard, ARIA, and the
+ * data-checked / data-disabled / data-indeterminate attributes the stylesheet
+ * hooks onto. It never supplies the API.
+ *
+ * Its parts accept className, style and a render prop on every element, by
+ * design, because they are unstyled primitives. None of that is forwarded. That
+ * refusal is the wrapper's whole job, and a boundary rule stops anyone walking
+ * round it by importing the primitive directly.
+ *
+ * Controlled only. An uncontrolled mode would mean two sources of truth for
+ * whether the box is ticked, and the bug that produces is invisible in review.
+ */
+export type CheckboxProps = {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  label: string;
+  id: string;
+  name?: string;
+  disabled?: boolean;
+  indeterminate?: boolean;
+};
+
+export function Checkbox({ checked, onChange, label, id, name, disabled = false, indeterminate = false }: CheckboxProps) {
+  return (
+    <span data-ds="checkbox">
+      <Base.Root
+        id={id}
+        name={name}
+        checked={checked}
+        indeterminate={indeterminate}
+        disabled={disabled}
+        onCheckedChange={onChange}
+      >
+        {/* The mark is drawn entirely by CSS from the data-* attributes. */}
+        <Base.Indicator />
+      </Base.Root>
+      <label htmlFor={id}>{label}</label>
+    </span>
+  );
+}
+`,
+
+    "Select.tsx": `"use client";
+${GENERATED("closed prop surface, and the portal's theme lookup")}
+import { useRef } from "react";
+import { Select as Base } from "${primitive}/select";
+
+/**
+ * A portalled primitive, which is why this file exists in the seed set.
+ *
+ * THE BUG THIS SHIPS ALREADY FIXED. A popup renders in a portal, outside the
+ * DOM subtree of the surface that opened it — so inheritance-based theming stops
+ * reaching it and the popup opens light against a dark panel. Found by looking
+ * at a deployed catalogue; no unit test would have caught it.
+ *
+ * The fix is to portal into the nearest themed container rather than the body:
+ * \`trigger.closest("[data-theme]")\`. That works because the token stylesheet
+ * emits [data-theme] as an unqualified selector, so it applies on any element
+ * and not only on :root.
+ */
+export type SelectOption = { value: string; label: string };
+
+export type SelectProps = {
+  value: string;
+  onChange: (value: string) => void;
+  options: readonly SelectOption[];
+  label: string;
+  disabled?: boolean;
+  name?: string;
+};
+
+export function Select({ value, onChange, options, label, disabled = false, name }: SelectProps) {
+  const trigger = useRef<HTMLDivElement>(null);
+
+  return (
+    <div ref={trigger} data-ds="select">
+      <Base.Root
+        value={value}
+        name={name}
+        disabled={disabled}
+        // The primitive can clear to null; this control has no clear affordance,
+        // so narrowing here keeps the callback honest about what can happen.
+        onValueChange={(next) => { if (next !== null) onChange(next as string); }}
+      >
+        <Base.Trigger aria-label={label}>
+          <Base.Value />
+        </Base.Trigger>
+        <Base.Portal container={() => trigger.current?.closest("[data-theme]") ?? null}>
+          <Base.Positioner>
+            <Base.Popup>
+              {options.map((o) => (
+                <Base.Item key={o.value} value={o.value}>
+                  <Base.ItemText>{o.label}</Base.ItemText>
+                </Base.Item>
+              ))}
+            </Base.Popup>
+          </Base.Positioner>
+        </Base.Portal>
+      </Base.Root>
+    </div>
+  );
+}
+`,
+  };
+}
+
+/**
+ * The closure test.
+ *
+ * It reads the emitted source AS TEXT rather than importing it, for the same
+ * reason System A's does: a typo'd prop name would resolve to
+ * `undefined` through an import and the assertion would pass while the rule it
+ * checks had quietly stopped applying.
+ */
+function setTest(components) {
+  return `${GENERATED("rule this file enforces — it runs on every commit, not at emission")}
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const COMPONENTS = ${JSON.stringify(components)};
+
+/**
+ * THE LOAD-BEARING RULE.
+ *
+ * "No className passthrough. This is the load-bearing one. It is the escape
+ * hatch that quietly makes every other rule advisory, and a system with it is a
+ * folder of components with extra steps."
+ *
+ * Source is read as text, not imported: a typo'd prop name resolves to undefined
+ * through an import, so an import-based check passes while the rule it is
+ * checking has stopped applying.
+ *
+ * These components are EXPECTED to be edited. That is why this runs on every
+ * commit rather than at emission — closure has to survive the editing, or it was
+ * only ever a property of the first commit.
+ */
+const FORBIDDEN = /\\b(className|style|radius|colour|color|padding|margin|width|height|boxShadow|render)\\s*[?:]/;
+
+for (const name of COMPONENTS) {
+  test(\`\${name} accepts no style-shaped prop\`, () => {
+    const src = readFileSync(join(HERE, \`\${name}.tsx\`), "utf8");
+    const propBlocks = src.match(/export type \\w+Props = \\{[^}]*\\}/gs) ?? [];
+    assert.ok(propBlocks.length > 0, \`\${name} exports no Props type to check\`);
+    for (const block of propBlocks) {
+      const hit = block.match(FORBIDDEN);
+      assert.equal(hit, null,
+        \`\${name} accepts "\${hit?.[1]}" — a component that can be overridden will drift\`);
+    }
+  });
+}
+
+test("every component is exported from the barrel", () => {
+  const barrel = readFileSync(join(HERE, "index.ts"), "utf8");
+  for (const name of COMPONENTS) {
+    assert.match(barrel, new RegExp(\`\\\\b\${name}\\\\b\`), \`\${name} is not exported\`);
+  }
+});
+`;
+}
+
+function stylesheet(dict) {
+  const v = (g, n) => `var(${varName(g, n)})`;
+  return `${GENERATED("absence of any literal value in this file")}
+
+/* Every value here is a var(). The audit asserts it, so a hex or a raw px in
+ * this file fails the build rather than becoming the first crack. */
+
+[data-ds="card"] {
+  border-radius: ${v("radius", "card")};
+  border: ${v("border", "hair")} solid ${v("color", "border")};
+  background: ${v("color", "raised")};
+  color: ${v("color", "text")};
+}
+[data-ds="card"][data-inset="sm"] { padding: ${v("space", 3)}; }
+[data-ds="card"][data-inset="md"] { padding: ${v("space", 5)}; }
+[data-ds="card"][data-inset="lg"] { padding: ${v("space", 6)}; }
+[data-ds="card"][data-tone="muted"]  { background: ${v("color", "inset")}; }
+[data-ds="card"][data-tone="danger"] { border-color: ${v("color", "danger")}; }
+
+/* The themed tone reads the runtime theme, with the dictionary as the fallback.
+ * The fallback must be a literal var() reference rather than a value, so an
+ * unthemed surface still renders from the dictionary. */
+[data-ds="card"][data-tone="themed"] {
+  background: var(--theme-surface, ${v("color", "raised")});
+  border-color: var(--theme-border, ${v("color", "border")});
+  color: var(--theme-text, ${v("color", "text")});
+}
+
+[data-ds="button"] {
+  border-radius: ${v("radius", "control")};
+  font-size: ${v("text", "body")};
+  font-weight: ${v("weight", "medium")};
+  padding: ${v("space", 3)} ${v("space", 5)};
+}
+[data-ds="button"][data-size="sm"] { font-size: ${v("text", "small")}; padding: ${v("space", 2)} ${v("space", 4)}; }
+[data-ds="button"][data-tone="accent"][data-emphasis="filled"] {
+  background: ${v("color", "accent")};
+  color: ${v("color", "onAccent")};
+}
+[data-ds="button"][data-tone="danger"][data-emphasis="filled"] {
+  background: ${v("color", "danger")};
+  color: ${v("color", "onAccent")};
+}
+[data-ds="button"][data-emphasis="ghost"] { background: transparent; }
+
+[data-ds="text"][data-role="body"]    { font-size: ${v("text", "body")};    line-height: ${v("lineHeight", "body")};  color: ${v("color", "text")}; }
+[data-ds="text"][data-role="muted"]   { font-size: ${v("text", "body")};    color: ${v("color", "muted")}; }
+[data-ds="text"][data-role="faint"]   { font-size: ${v("text", "small")};   color: ${v("color", "faint")}; }
+[data-ds="text"][data-role="title"]   { font-size: ${v("text", "title")};   line-height: ${v("lineHeight", "flush")}; }
+[data-ds="text"][data-role="display"] { font-size: ${v("text", "display")}; line-height: ${v("lineHeight", "flush")}; }
+
+[data-ds="checkbox"], [data-ds="select"] { font-size: ${v("text", "body")}; }
+[data-ds="select"] [role="listbox"] {
+  border-radius: ${v("radius", "card")};
+  background: ${v("color", "raised")};
+  box-shadow: ${v("shadow", "overlay")};
+}
+`;
+}
+
+export function emitSystem({ dict = SEED, primitive = "@base-ui/react", path = "packages/design-system", components = SEED_COMPONENTS, tokensPackage = "@scaffold/design-tokens", systemPackage = "@scaffold/design-system" } = {}) {
+  const sources = componentSources(primitive);
+  const out = {};
+
+  for (const name of components) {
+    const src = sources[`${name}.tsx`];
+    if (!src) throw new Error(`No seed template for "${name}". The seed set is a menu, not a catalogue — add a template or drop it from the list.`);
+    out[`${path}/src/${name}.tsx`] = src;
+  }
+
+  out[`${path}/src/theme.ts`] = themeModule(dict);
+  out[`${path}/src/theme.test.ts`] = themeTest;
+  out[`${path}/src/defaults.ts`] = defaultsModule;
+  out[`${path}/src/styles.css`] = stylesheet(dict);
+  out[`${path}/src/set.test.ts`] = setTest(components);
+  out[`${path}/package.json`] = JSON.stringify({
+    name: systemPackage,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    main: "./src/index.ts",
+    types: "./src/index.ts",
+    exports: { ".": "./src/index.ts", "./styles.css": "./src/styles.css" },
+    // The primitive is a real dependency of THIS package and of nothing else —
+    // the boundary rule forbids an app from even declaring it.
+    dependencies: { [primitive]: "^1.0.0", [tokensPackage]: "workspace:*" },
+    peerDependencies: { react: "^19.0.0" },
+    scripts: { test: "node --test src/*.test.ts" },
+  }, null, 2) + "\n";
+
+  out[`${path}/src/index.ts`] =
+`${GENERATED("completeness of this barrel — set.test.ts fails if a component is missing")}
+${components.map((n) => `export { ${n} } from "./${n}";\nexport type { ${n}Props } from "./${n}";`).join("\n")}
+export { themeVars, themeVar } from "./theme";
+export type { SurfaceTheme, ThemeSlot } from "./theme";
+`;
+  return out;
+}
+
+/* ------------------------------------------------------------------ config */
+
+/**
+ * Paths that are written once and never upgraded.
+ *
+ * `gyde.config.json` is the PRODUCT's configuration, not a template: Gyde has
+ * no version of it to ship. Recording it as provenance made an upgrade report
+ * it as "retired" — a file this version no longer emits — which is both wrong
+ * and alarming, since the retired list is where a reader looks for things that
+ * were dropped.
+ *
+ * The rule: provenance is for files Gyde has an opinion about the CONTENTS of.
+ */
+export const NOT_UPGRADEABLE = new Set(["gyde.config.json"]);
+
+export function emitConfig({ systemPath = "packages/design-system", tokensPath = "packages/design-tokens", foreignPaths = [], primitive = "@base-ui/react", scope = null, defaultBranch = null, runsOn = null } = {}) {
+  return {
+    "gyde.config.json": JSON.stringify({
+      version: 1,
+      design: {
+        primitive,
+        // Recorded so the next run does not have to re-derive it, and so a
+        // workspace that adds a second scope does not silently change what the
+        // emitted code imports.
+        scope,
+        systemPath,
+        tokensPath,
+        /**
+         * Detected once, then recorded — for the same reason as `scope` above,
+         * and G-66 is what made the reason concrete.
+         *
+         * These two are DETECTED from the repository: the default branch from
+         * git, the runner from the existing workflows. Detection is right at
+         * `init`, and re-running it on every `upgrade` is how a workflow gets
+         * silently rewritten. System B had `branches: [staging, main]`
+         * on disk; a later `upgrade` re-detected `staging` alone and proposed
+         * to revert the promotion trigger, reporting it as "Gyde changed and
+         * you had not touched" — when a person had changed it deliberately.
+         *
+         * Recorded here, the emitted workflow is reproducible from committed
+         * configuration, so an upgrade at the same version is a genuine no-op
+         * and a real change is a real diff.
+         */
+        defaultBranch,
+        runsOn,
+        // Both of these SUPPRESS findings, so a wrong value here is a silent
+        // pass. They are committed configuration a reviewer can see and argue
+        // with — never something Gyde infers from a path heuristic.
+        systemPaths: [systemPath, tokensPath],
+        foreignPaths,
+      },
+    }, null, 2) + "\n",
+  };
+}