@multiplatform.one/config 7.34.4 → 7.36.0

package/lint.mjs

@@ -70,6 +70,15 @@
  *    `mpo-conventions/no-hex-literals`, whose file and reason are not a row
  *    in the spec's `## Colour-literal escapes` table, or a row whose comment
  *    is gone.
+ * 14. Fail on a RETIRED SCALE KNOB (LC-100 TOKEN-SCALE) — a `size`, `space`
+ *    or `density` key in a knob literal (`<Preset overrides>`, a `knobs:`
+ *    block, a `Knobs` / `StateKnobs` / `Preset` / `IntentOverride` typed
+ *    literal or a `registerPreset` call), a `density: "compact"` value, a
+ *    `compact` prop on a house component, a `data-density` attribute, or a
+ *    `<Surface>` given `density` or a word size (`sm`, `small`, `medium`, …).
+ *    Size, spacing and radius are the preset's token scale; the only
+ *    per-site control is Tamagui's own `size="$n"`. Specs are exempt: they
+ *    are where the retirement is asserted.
  *
  * Usage:
  *   import { runConventionChecks } from "@multiplatform.one/config/lint";
@@ -311,8 +320,8 @@ function sliceBlock(src, marker, end) {
 function keysOfBlock(body, indent) {
   /** @type {string[]} */
   const keys = [];
-  const re = new RegExp(`^ {${indent}}([A-Za-z0-9][A-Za-z0-9]*)\\s*:`, "gm");
-  for (const m of body.matchAll(re)) keys.push(m[1]);
+  const re = new RegExp(`^ {${indent}}(?:"([^"\\r\\n]+)"|([A-Za-z0-9][A-Za-z0-9]*))\\s*:`, "gm");
+  for (const m of body.matchAll(re)) keys.push(m[1] ?? m[2]);
   return keys;
 }
 
@@ -365,7 +374,7 @@ function scanLiterals(re, check) {
 }
 
 /**
- * The animation vocabulary is a CLOSED set (css.ts / reactNative.ts register
+ * The animation vocabulary is a CLOSED set (motionTiming.ts / reactNative.ts register
  * exactly these keys). A `transition="X"` with an X outside the set is not a
  * type error — Tamagui silently ignores the unknown animation name, so the
  * element renders with NO animation. That is invisible until someone notices
@@ -377,7 +386,7 @@ function scanLiterals(re, check) {
 function readAnimationTokens() {
   /** @type {Set<string>} */
   const tokens = new Set();
-  const src = readPublicSource("theme/src/theme/animations/css.ts");
+  const src = readPublicSource("theme/src/theme/motionTiming.ts");
   if (!src) return tokens;
   tokens.add("none"); // valid non-animating value
   for (const key of keysOfBlock(sliceBlock(src, "animationConfig =", "} as const"), 2)) {
@@ -391,7 +400,7 @@ function checkTransitionTokens() {
   const valid = readAnimationTokens();
   if (!valid.size) return { violations: [], valid: [], ok: false };
   // Only string LITERALS directly on the prop — dynamic values (variables,
-  // ternaries, knobProps.transition) resolve at runtime and are out of scope.
+  // ternaries, knobProps.motion.control.transition) resolve at runtime and are out of scope.
   const re = /\btransition=(?:"([a-zA-Z0-9]+)"|\{\s*"([a-zA-Z0-9]+)"\s*\})/g;
   const violations = scanLiterals(re, (m) => {
     const token = m[1] ?? m[2];
@@ -400,88 +409,70 @@ function checkTransitionTokens() {
   return { violations, valid: [...valid].filter((t) => t !== "none").sort(), ok: true };
 }
 
-/**
- * Every registered Tamagui theme name, plus each sub-theme SEGMENT a `theme`
- * prop may name on its own (`theme="accent"` selects `light_accent` under the
- * light scheme). Rebuilt from the same three sources `createThemesBuilder`
- * composes: the theme-builder's generated names for this base/children/accent
- * shape, the stock `@tamagui/themes` names, and the gray aliases declared in
- * createThemes.ts. Palettes are irrelevant here — only the NAMES are.
- * @returns {Set<string>}
- */
-function readThemeNames() {
-  /** @type {Set<string>} */
-  const names = new Set();
+function readThemeMatrix() {
   const builder = tryRequire("@tamagui/theme-builder");
-  const stock = tryRequire("@tamagui/themes");
+  const v5 = tryRequire("@tamagui/themes/v5");
   const src = readPublicSource("theme/src/theme/createThemes.ts");
-  if (!builder?.createThemes || !stock?.themes || !src) return names;
-  const ramp = Array.from({ length: 14 }, (_, i) => `hsl(0, 0%, ${i * 7}%)`);
-  const palette = { palette: { dark: ramp, light: ramp } };
-  /** @type {Record<string, unknown>} */
-  const childrenThemes = {};
+  if (!builder?.createThemes || !v5?.defaultChildrenThemes || !src) return {};
+  const childrenHues = src.match(/const childrenHues = \[([^\]]+)\]/)?.[1];
+  if (!childrenHues) return {};
+  const palette = { palette: { dark: v5.defaultDarkPalette, light: v5.defaultLightPalette } };
+  const childrenThemes = Object.fromEntries(
+    [...childrenHues.matchAll(/"([a-z]+)"/g)].map(([, name]) => [name, palette]),
+  );
   for (const key of keysOfBlock(sliceBlock(src, "const childrenThemes =", "\n  };"), 4)) {
     childrenThemes[key] = palette;
   }
+  const templatesOf = (name) =>
+    Object.fromEntries(
+      [
+        ...sliceBlock(src, `export const ${name} =`, "} as const").matchAll(
+          /^ {2}(\w+): \{ template: "(\w+)" \}/gm,
+        ),
+      ].map((match) => [match[1], { template: match[2] }]),
+    );
   try {
-    for (const name of Object.keys(
-      builder.createThemes({ base: palette, childrenThemes, accent: palette }),
-    )) {
-      names.add(name);
-    }
+    return builder.createThemes({
+      templates: v5.v5Templates,
+      componentThemes: templatesOf("houseComponentThemes"),
+      grandChildrenThemes: templatesOf("houseGrandChildrenThemes"),
+      base: palette,
+      childrenThemes,
+      accent: palette,
+    });
   } catch {
-    return new Set();
-  }
-  for (const name of Object.keys(stock.themes)) names.add(name);
-  for (const m of sliceBlock(src, "const grayTheme =", "\n};").matchAll(
-    /^ {2}([a-zA-Z][a-zA-Z0-9_]*)\s*:/gm,
-  )) {
-    names.add(m[1]);
+    return {};
   }
-  /** @type {string[]} */
-  const segments = [];
-  for (const name of names) for (const part of name.split("_").slice(1)) segments.push(part);
-  for (const segment of segments) names.add(segment);
-  return names;
 }
 
-/**
- * Every key resolvable as `$value` on a color-bearing prop, composed exactly
- * the way `createThemesBuilder` composes the live themes: the structural keys
- * the theme-builder generates (colorN / background0N / accentN / …), the stock
- * base themes, the Radix ramps createThemes.ts splats into `extra`, the shadow
- * slots, and the project's semantic aliases from `getBaseTheme`.
- * @returns {Set<string>}
- */
+/** Names and sub-theme segments must come from the same v5 matrix as the builder. */
+function readThemeNames() {
+  const names = Object.keys(readThemeMatrix());
+  return new Set(names.flatMap((name) => [name, ...name.split("_").slice(1)]));
+}
+
 function readThemeKeys() {
   /** @type {Set<string>} */
   const keys = new Set();
-  const builder = tryRequire("@tamagui/theme-builder");
-  const stock = tryRequire("@tamagui/themes");
-  const colors = tryRequire("@tamagui/colors");
+  const v5 = tryRequire("@tamagui/themes/v5");
   const src = readPublicSource("theme/src/theme/createThemes.ts");
   const builderSrc = readPublicSource("theme/src/theme/defaults/builderOptions.ts");
-  if (!builder?.createThemes || !stock?.themes || !colors || !src || !builderSrc) return keys;
-  const ramp = Array.from({ length: 14 }, (_, i) => `hsl(0, 0%, ${i * 7}%)`);
-  const palette = { palette: { dark: ramp, light: ramp } };
-  try {
-    const generated = builder.createThemes({
-      base: palette,
-      childrenThemes: { warning: palette },
-      accent: palette,
-    });
-    for (const theme of Object.values(generated)) for (const k of Object.keys(theme)) keys.add(k);
-  } catch {
-    return new Set();
+  const matrix = readThemeMatrix();
+  if (!Object.keys(matrix).length || !v5?.defaultChildrenThemes || !builderSrc) return keys;
+  for (const theme of Object.values(matrix)) {
+    for (const key of Object.keys(theme)) keys.add(key);
   }
-  for (const name of ["light", "dark"]) {
-    for (const k of Object.keys(stock.themes[name] ?? {})) keys.add(k);
-  }
-  for (const m of src.matchAll(/\.\.\.Colors\.([A-Za-z0-9]+)\s*,/g)) {
-    for (const k of Object.keys(colors[m[1]] ?? {})) keys.add(k);
+  for (const theme of Object.values(v5.defaultChildrenThemes)) {
+    for (const scheme of ["light", "dark"]) {
+      for (const key of Object.keys(theme[scheme])) keys.add(key);
+    }
   }
   for (const k of keysOfBlock(sliceBlock(src, "export interface Shadows", "\n}"), 2)) keys.add(k);
   keys.add("shadowColor");
+  const syntaxHues = src.match(/const syntaxInkHues = \[([^\]]+)\]/)?.[1] ?? "";
+  for (const [, hue] of syntaxHues.matchAll(/"([a-z]+)"/g)) {
+    keys.add(`syntax${hue[0].toUpperCase()}${hue.slice(1)}`);
+  }
   for (const k of keysOfBlock(sliceBlock(builderSrc, "function getBaseTheme", "\n}"), 4))
     keys.add(k);
   return keys;
@@ -665,7 +656,7 @@ function checkAnimationProps() {
     const src = readFileSync(filePath, "utf8");
     const rel = relative(ROOT, filePath);
     // Any `…transition`-valued animation key, so prefixed spellings like
-    // `ctx.knobProps.transition` are caught too. Deliberately NOT "any value":
+    // `ctx.knobProps.motion.control.transition` are caught too. Deliberately NOT "any value":
     // that also matches TS annotations (`animation: any`), css-in-js, and
     // unrelated config objects that have nothing to do with the tamagui prop.
     // The lookbehind keeps `data-animation={…}` (probe attributes: Spinner,
@@ -1455,6 +1446,19 @@ function nonCommentOffsets(src) {
       i += 2;
       continue;
     }
+    if (char === '"' || char === "'" || char === "`") {
+      const quote = char;
+      i++;
+      while (i < src.length) {
+        if (src[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (quote !== "`" && src[i] === "\n") break;
+        if (src[i++] === quote) break;
+      }
+      continue;
+    }
     i++;
   }
   return mask;
@@ -1582,6 +1586,513 @@ function checkStoryForeignControls() {
   return violations;
 }
 
+// ── Retired scale knobs (LC-100 TOKEN-SCALE) ─────────────────────────────
+
+const RETIRED_SCANNED_RE = /\.(tsx|ts|jsx|js|mjs)$/;
+const WORD_SIZES = new Set(["sm", "small", "md", "medium", "lg", "large"]);
+const KNOB_LITERAL_OPENERS = [
+  /\bknobs\s*:\s*\{/g,
+  /:\s*(?:Partial<\s*)?(?:Knobs|StateKnobs|Preset|IntentOverride)\s*>?\s*=\s*\{/g,
+  /\bregisterPreset\(\s*[^,()]+,\s*\{/g,
+];
+const KNOB_KEY_RE = /(?:^|[\s{,(])(["']?)(size|space|density)\1\s*:/g;
+const DENSITY_VALUE_RE = /\bdensity\s*:\s*["'](?:compact|comfortable)["']/g;
+const HOUSE_IMPORT_RE = /import\s+(?!type\b)([^;'"]*?)from\s*["']@multiplatform\.one\/[^"']+["']/g;
+
+/**
+ * Index just past the brace that closes the one at `open`, skipping strings
+ * and comments. `src.length` when it never closes.
+ * @param {string} src
+ * @param {number} open
+ */
+function closingBrace(src, open) {
+  const mask = codeOffsets(src.slice(open));
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (mask[i - open] !== 1) continue;
+    if (src[i] === "{") depth++;
+    else if (src[i] === "}" && --depth === 0) return i + 1;
+  }
+  return src.length;
+}
+
+/**
+ * The attribute text of the JSX opening tag whose `<` is at `start`, with
+ * braces balanced so an arrow inside a prop does not end it.
+ * @param {string} src
+ * @param {Uint8Array} mask
+ * @param {number} start
+ */
+function openingTag(src, mask, start) {
+  let depth = 0;
+  for (let i = start + 1; i < src.length; i++) {
+    const char = src[i];
+    if (char === '"' || char === "'") {
+      if (depth === 0) {
+        const close = src.indexOf(char, i + 1);
+        if (close === -1) return src.slice(start);
+        i = close;
+      }
+      continue;
+    }
+    if (mask[i] !== 1) continue;
+    if (char === "{") depth++;
+    else if (char === "}") depth--;
+    else if (char === ">" && depth === 0) return src.slice(start, i + 1);
+  }
+  return src.slice(start);
+}
+
+/**
+ * Top-level attribute names of an opening tag (outside `{…}`, quotes and
+ * comments), with their literal string values.
+ * @param {string} raw
+ */
+function tagAttributes(raw) {
+  /** @type {Map<string, string>} */
+  const attrs = new Map();
+  const live = nonCommentOffsets(raw);
+  const tag = raw
+    .split("")
+    .map((char, i) => (live[i] === 1 || char === "\n" ? char : " "))
+    .join("");
+  let depth = 0;
+  let flat = "";
+  for (let i = 0; i < tag.length; i++) {
+    const char = tag[i];
+    if (char === "{") depth++;
+    if (depth > 0) {
+      flat += char === "\n" ? "\n" : " ";
+      if (char === "}") depth--;
+      continue;
+    }
+    flat += char;
+  }
+  for (const m of flat.matchAll(/\s([A-Za-z][\w-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|\s))?/g)) {
+    attrs.set(m[1], m[2] ?? m[3] ?? "");
+  }
+  for (const m of tag.matchAll(/\s([A-Za-z][\w-]*)\s*=\s*\{\s*["']([^"']*)["']\s*\}/g)) {
+    attrs.set(m[1], m[2]);
+  }
+  return attrs;
+}
+
+/**
+ * Local names bound by value imports from `@multiplatform.one/*`.
+ * @param {string} src
+ */
+function houseImportNames(src) {
+  const names = new Set();
+  for (const statement of src.matchAll(HOUSE_IMPORT_RE)) {
+    const clause = statement[1];
+    const named = clause.match(/\{([\s\S]*)\}/);
+    const bare = clause.replace(/\{[\s\S]*\}/, "").replace(/\*\s+as\s+/, "");
+    for (const part of bare.split(",")) {
+      const name = part.trim();
+      if (name) names.add(name);
+    }
+    if (!named) continue;
+    for (const specifier of named[1].split(",")) {
+      const entry = specifier.trim();
+      if (!entry || /^type\b/.test(entry)) continue;
+      const [imported, alias] = entry.split(/\s+as\s+/).map((part) => part.trim());
+      names.add(alias || imported);
+    }
+  }
+  return names;
+}
+
+/**
+ * LC-100: the size, space and density knobs are gone. A preset that needs
+ * more or less room carries its own token scale; a use site picks a size
+ * token with Tamagui's `size="$n"`. Every retired form fails here so a stale
+ * copy cannot come back through a literal the type checker does not see
+ * (a cookie payload, a story global, an untyped spread).
+ */
+function checkRetiredScaleKnobs() {
+  /** @type {string[]} */
+  const violations = [];
+  const scan = (filePath, catalog) => {
+    if (!RETIRED_SCANNED_RE.test(filePath) || filePath.endsWith(".d.ts")) return;
+    if (/\.(spec|test)\./.test(filePath)) return;
+    const src = readFileSync(filePath, "utf8");
+    if (!/\b(?:size|space|density|compact)\b/.test(src)) return;
+    const rel = relative(ROOT, filePath).replaceAll("\\", "/");
+    const code = codeOffsets(src);
+    const live = nonCommentOffsets(src);
+    const report = (index, what) => violations.push(`${rel}:${lineAt(src, index)} — ${what}`);
+
+    /** @type {[number, number][]} */
+    const blocks = [];
+    for (const opener of KNOB_LITERAL_OPENERS) {
+      for (const m of src.matchAll(opener)) {
+        const open = (m.index ?? 0) + m[0].length - 1;
+        if (code[open] === 1) blocks.push([open, closingBrace(src, open)]);
+      }
+    }
+    for (const m of src.matchAll(/\boverrides\s*=\s*\{\{/g)) {
+      const open = (m.index ?? 0) + m[0].length - 1;
+      if (code[open] !== 1) continue;
+      const tagStart = src.lastIndexOf("<", m.index ?? 0);
+      if (!/^<Preset\b/.test(src.slice(tagStart))) continue;
+      blocks.push([open, closingBrace(src, open)]);
+    }
+    const seen = new Set();
+    for (const [open, close] of blocks) {
+      const body = src.slice(open, close);
+      for (const m of body.matchAll(KNOB_KEY_RE)) {
+        const colon = open + (m.index ?? 0) + m[0].length - 1;
+        if (code[colon] !== 1 || seen.has(colon)) continue;
+        seen.add(colon);
+        report(colon, `\`${m[2]}\` knob in a knob literal`);
+      }
+    }
+    for (const m of src.matchAll(DENSITY_VALUE_RE)) {
+      const index = m.index ?? 0;
+      if (code[index] !== 1) continue;
+      const colon = src.indexOf(":", index);
+      if (seen.has(colon)) continue;
+      report(index, `\`${m[0]}\``);
+    }
+    for (const m of src.matchAll(/data-density/g)) {
+      const index = m.index ?? 0;
+      if (live[index] === 1) report(index, "`data-density` attribute");
+    }
+
+    const house = houseImportNames(src);
+    for (const m of src.matchAll(/<([A-Z][\w]*)((?:\.[A-Z]\w*)*)\b/g)) {
+      const index = m.index ?? 0;
+      if (code[index] !== 1) continue;
+      const root = m[1];
+      const name = root + (m[2] ?? "");
+      const attrs = tagAttributes(openingTag(src, code, index));
+      if (root === "Surface") {
+        if (attrs.has("density")) report(index, "`<Surface density>`");
+        const size = attrs.get("size");
+        if (size !== undefined && WORD_SIZES.has(size)) {
+          report(index, `\`<Surface size="${size}">\` (a size token, \`$3\`)`);
+        }
+      }
+      if (attrs.has("compact") && (catalog || house.has(root))) {
+        report(index, `\`compact\` on <${name}> (a size token, \`size="$3"\`)`);
+      }
+    }
+  };
+  if (existsSync(PUBLIC_DIR)) {
+    for (const pkg of readdirSync(PUBLIC_DIR, { withFileTypes: true })) {
+      if (!pkg.isDirectory() || pkg.name.startsWith(".") || pkg.name === "node_modules") continue;
+      walkFiles(join(PUBLIC_DIR, pkg.name, "src"), (filePath) => scan(filePath, true));
+    }
+  }
+  for (const dir of [APPS_DIR, FEATURES_DIR, PACKAGES_DIR]) {
+    walkFiles(dir, (filePath) => scan(filePath, false));
+  }
+  return violations;
+}
+
+function walkOwnedSource(scan) {
+  if (existsSync(PUBLIC_DIR)) {
+    for (const pkg of readdirSync(PUBLIC_DIR, { withFileTypes: true })) {
+      if (!pkg.isDirectory() || pkg.name.startsWith(".") || pkg.name === "node_modules") continue;
+      walkFiles(join(PUBLIC_DIR, pkg.name, "src"), scan);
+    }
+  }
+  for (const dir of [FEATURES_DIR, PACKAGES_DIR, APPS_DIR]) walkFiles(dir, scan);
+}
+
+function shadowLiteralAt(src, start) {
+  let index = start;
+  while (/\s/.test(src[index] ?? "") && index < src.length) index++;
+  const quote = src[index];
+  if (quote !== '"' && quote !== "'" && quote !== "`") return undefined;
+  const begin = ++index;
+  while (index < src.length) {
+    if (src[index] === "\\") {
+      index += 2;
+      continue;
+    }
+    if (src[index] === quote) return src.slice(begin, index);
+    index++;
+  }
+  return undefined;
+}
+
+function checkOverlayOwnership() {
+  const shadows = [];
+  const frames = [];
+  const overlayTags = new Set([
+    "PopoverContent",
+    "DialogContent",
+    "AlertDialogContent",
+    "SheetFrame",
+    "Sheet.Frame",
+    "Popover.Content",
+    "Dialog.Content",
+    "AlertDialog.Content",
+    "Tooltip.Content",
+    "TooltipContent",
+  ]);
+  walkOwnedSource((filePath) => {
+    if (
+      !/\.(?:tsx?|jsx?|mjs)$/.test(filePath) ||
+      /\.(?:spec|test)\./.test(filePath) ||
+      filePath.endsWith(".d.ts")
+    )
+      return;
+    const src = readFileSync(filePath, "utf8");
+    if (!/boxShadow|Content|Sheet/.test(src)) return;
+    const rel = relative(ROOT, filePath).replaceAll("\\", "/");
+    const code = codeOffsets(src);
+    const exemptShadow =
+      rel === "public/theme/src/theme/resolveKnobs.ts" ||
+      rel.startsWith("public/connectkit/") ||
+      rel.startsWith("public/web3/src/connectkit/") ||
+      rel.startsWith("apps/one/webext/content_scripts/");
+    if (!exemptShadow) {
+      const bindings = new Map();
+      for (const match of src.matchAll(
+        /\b([A-Za-z_$][\w$]*)(?:\s*:\s*[^=;{}\n]+)?\s*=\s*(?=["'`])/g,
+      )) {
+        if (code[match.index] !== 1) continue;
+        bindings.set(match[1], shadowLiteralAt(src, match.index + match[0].length));
+      }
+      for (const match of src.matchAll(/(?:\bboxShadow|["']boxShadow["'])\s*[:=]\s*/g)) {
+        const separator = match.index + match[0].search(/[:=]/);
+        if (code[separator] !== 1) continue;
+        let start = match.index + match[0].length;
+        if (src[separator] === "=" && src[start] === "{") start++;
+        let value = shadowLiteralAt(src, start);
+        if (value === undefined) {
+          const identifier = /^\s*([A-Za-z_$][\w$]*)/.exec(src.slice(start));
+          if (identifier && !/^[.([?]/.test(src.slice(start + identifier[0].length).trimStart())) {
+            value = bindings.get(identifier[1]);
+          }
+        }
+        if (value && /\d+(?:\.\d+)?px|\b0\s+0\b|rgba?|hsla?|#/i.test(value)) {
+          shadows.push(
+            `${rel}:${lineAt(src, match.index)} — owned boxShadow literal; spread knobProps.elevatedSurface, elevationChrome or thumbShadow`,
+          );
+        }
+      }
+    }
+    if (!/\.(?:tsx|jsx)$/.test(filePath)) return;
+    for (const match of src.matchAll(/<([A-Z][\w]*(?:\.[A-Z][\w]*)*)\b/g)) {
+      if (code[match.index] !== 1) continue;
+      const name = match[1];
+      if (
+        /^(?:Popover|Dialog|AlertDialog)\.Content$/.test(name) &&
+        rel !== "public/theme/src/theme/overlaySurfaces.tsx"
+      ) {
+        frames.push(
+          `${rel}:${lineAt(src, match.index)} — raw <${name}>; use the house frame from @multiplatform.one/theme or @multiplatform.one/components`,
+        );
+      }
+      if (!overlayTags.has(name)) continue;
+      const tag = openingTag(src, code, match.index);
+      const elevation =
+        /\belevation\s*=\s*\{[^}]*\bknobProps\.(?:elevation|overlayElevation)\b/.exec(tag);
+      if (elevation && code[match.index + elevation.index] === 1) {
+        frames.push(
+          `${rel}:${lineAt(src, match.index + elevation.index)} — elevation overrides the house <${name}> frame; let its elevatedSurface recipe paint`,
+        );
+      }
+    }
+  });
+  return { shadows, frames };
+}
+
+/**
+ * Run structural convention checks over a consumer tree.
+ *
+ * @param {RunConventionChecksOptions} [options]
+ * @returns {number} 0 when clean, 1 when any check failed
+ */
+// ── Layout rules (LC-101 … LC-103, FZ-7158 WP-h) ──────────────────────────
+
+/** Ratchet for the layout rules that land on a tree already breaking them. */
+const LAYOUT_BASELINES = "docs/layout-rule-baselines.json";
+
+/**
+ * `null` when the baseline file is absent (a scaffolded project prunes
+ * docs/), and the layout checks then skip, like the spec registries.
+ * @returns {{ secondSidebar: string[], hugContent: Record<string, number> } | null}
+ */
+function readLayoutBaselines() {
+  const path = join(ROOT, LAYOUT_BASELINES);
+  if (!existsSync(path)) return null;
+  const raw = JSON.parse(readFileSync(path, "utf8"));
+  return {
+    secondSidebar: Array.isArray(raw.secondSidebar) ? raw.secondSidebar : [],
+    hugContent: raw.hugContent && typeof raw.hugContent === "object" ? raw.hugContent : {},
+  };
+}
+
+/** Screen code: where a page composes chrome (not the catalog primitives). */
+function isScreenSource(rel) {
+  const path = rel.replaceAll("\\", "/");
+  return (
+    path.startsWith("public/backoffice/src/") ||
+    path.startsWith("public/frappe-ui/src/") ||
+    path.startsWith("apps/") ||
+    path.startsWith("features/")
+  );
+}
+
+const SIDEBAR_TAG_RE = /<([A-Z][A-Za-z0-9]*Sidebar(?:Panel)?)(?=[\s/>])/g;
+
+/**
+ * LC-101 ONE-SIDEBAR: a page renders no sidebar column of its own beside
+ * the shell's nav. A `<…Sidebar>` / `<…SidebarPanel>` element in screen code
+ * is legal in a shell (`*Shell.tsx`, which owns the one column), in the
+ * sidebar's own file, or in a file that hands it to the shell through
+ * `useShellSidebarPanel`. The sites that predate the rule are the
+ * `secondSidebar` rows of docs/layout-rule-baselines.json; a row whose
+ * site is gone fails too.
+ */
+function checkOneSidebar() {
+  const baselines = readLayoutBaselines();
+  if (!baselines) return [];
+  const allowed = new Map(baselines.secondSidebar.map((file) => [file, false]));
+  /** @type {string[]} */
+  const violations = [];
+  for (const { rel, src } of sourceFiles()) {
+    const path = rel.replaceAll("\\", "/");
+    if (!isScreenSource(path) || !path.endsWith(".tsx") || /\.stories\./.test(path)) continue;
+    const base = path.split("/").pop() ?? "";
+    if (/Shell\.tsx$/.test(base) || /Sidebar(Panel)?\.tsx$/.test(base)) continue;
+    const mask = codeOffsets(src);
+    const hits = [...src.matchAll(SIDEBAR_TAG_RE)].filter((m) => mask[m.index ?? 0] === 1);
+    if (hits.length === 0) continue;
+    if (src.includes("useShellSidebarPanel(")) continue;
+    if (allowed.has(path)) {
+      allowed.set(path, true);
+      continue;
+    }
+    for (const m of hits) {
+      violations.push(
+        `${path}:${lineAt(src, m.index ?? 0)} — <${m[1]}> opens a second sidebar column; stack it under the shell nav with useShellSidebarPanel`,
+      );
+    }
+  }
+  for (const [file, seen] of allowed) {
+    if (!seen) violations.push(`${file} — secondSidebar baseline row has no site (stale row)`);
+  }
+  return violations;
+}
+
+const SPREAD_JUSTIFY_RE =
+  /justifyContent(?:\s*=\s*\{?\s*|\s*:\s*)["'](space-between|space-around|space-evenly)["']/g;
+
+/**
+ * LC-102 HUG-CONTENT: rows and columns hug their content; a spread
+ * justification (`space-between` / `-around` / `-evenly`) pushes a value
+ * away from its label. Ratcheted: each file may carry at most its
+ * `hugContent` count from docs/layout-rule-baselines.json, and a file that
+ * dropped below its row must lower it, so the count only goes down.
+ */
+function checkHugContent() {
+  const baselines = readLayoutBaselines();
+  if (!baselines) return [];
+  /** @type {string[]} */
+  const violations = [];
+  const seen = new Set();
+  for (const { rel, src } of sourceFiles()) {
+    const path = rel.replaceAll("\\", "/");
+    if (!/\.(tsx|ts)$/.test(path) || /\.stories\./.test(path)) continue;
+    const live = nonCommentOffsets(src);
+    const hits = [...src.matchAll(SPREAD_JUSTIFY_RE)].filter((m) => live[m.index ?? 0] === 1);
+    const allowed = baselines.hugContent[path] ?? 0;
+    if (allowed > 0) seen.add(path);
+    if (hits.length > allowed) {
+      const first = hits[allowed] ?? hits[0];
+      violations.push(
+        `${path}:${lineAt(src, first.index ?? 0)} — justifyContent="${first[1]}" (${hits.length} in file, baseline ${allowed}); hug the content with a gap instead`,
+      );
+    } else if (hits.length < allowed) {
+      violations.push(
+        `${path} — ${hits.length} spread justifications, baseline says ${allowed}; lower its hugContent row`,
+      );
+    }
+  }
+  for (const [file, count] of Object.entries(baselines.hugContent)) {
+    if (count > 0 && !seen.has(file)) {
+      violations.push(`${file} — hugContent baseline row has no file (stale row)`);
+    }
+  }
+  return violations;
+}
+
+const PHONE_HIDE_RE = /\$max-(?:xs|sm|md)\s*=\s*\{\{\s*display\s*:\s*["']none["']/;
+const WIDE_REVEAL_RE = /\$(?:sm|md|lg)\s*=\s*\{\{\s*display\s*:\s*["'](?!none)/;
+const HIDDEN_ATTR_RE = /\sdisplay\s*=\s*(?:\{\s*)?["']none["']/;
+
+/**
+ * LC-103 RESPONSIVE-PARITY: a phone shows the same information. An element
+ * hidden only on phones (`$max-sm={{ display: "none" }}`, or `display="none"`
+ * revealed by `$sm`/`$md`/`$lg`) must say where its phone twin is with a
+ * `responsive-parity: <reason>` comment inside the tag or on the line above
+ * (the ⋯ menu entry, the icon twin, the sheet that carries it).
+ */
+function checkResponsiveParity() {
+  if (!readLayoutBaselines()) return [];
+  /** @type {string[]} */
+  const violations = [];
+  for (const { rel, src } of sourceFiles()) {
+    const path = rel.replaceAll("\\", "/");
+    if (!isScreenSource(path) || !path.endsWith(".tsx") || /\.stories\./.test(path)) continue;
+    if (!src.includes("display")) continue;
+    const mask = codeOffsets(src);
+    for (const m of src.matchAll(/<[A-Za-z][\w.]*/g)) {
+      const start = m.index ?? 0;
+      if (mask[start] !== 1) continue;
+      const tag = openingTag(src, mask, start);
+      const hidesOnPhone =
+        PHONE_HIDE_RE.test(tag) || (HIDDEN_ATTR_RE.test(tag) && WIDE_REVEAL_RE.test(tag));
+      if (!hidesOnPhone) continue;
+      const lineStart = src.lastIndexOf("\n", start - 1);
+      const prevLineStart = src.lastIndexOf("\n", lineStart - 1);
+      const context = src.slice(Math.max(0, prevLineStart), start) + tag;
+      if (/responsive-parity:\s*\S/.test(context)) continue;
+      violations.push(
+        `${path}:${lineAt(src, start)} — hidden on phones with no \`responsive-parity: <reason>\` naming its phone twin`,
+      );
+    }
+  }
+  return violations;
+}
+
+function checkAccentSolidOwners() {
+  const owners = new Set([
+    "public/components/src/componentColors.ts",
+    "public/forms/src/shared/colorRamps.ts",
+    "public/theme/src/theme/createThemes.ts",
+    "public/theme/src/theme/chartPalette.ts",
+    "public/theme/src/theme/readableColor.ts",
+  ]);
+  const violations = [];
+  const scan = (filePath) => {
+    if (!/\.(ts|tsx|js|jsx|mjs)$/.test(filePath) || filePath.endsWith(".d.ts")) return;
+    if (/\.(spec|test|stories)\./.test(filePath)) return;
+    const rel = relative(ROOT, filePath).replaceAll("\\", "/");
+    if (owners.has(rel)) return;
+    const src = readFileSync(filePath, "utf8");
+    const live = nonCommentOffsets(src);
+    for (const match of src.matchAll(/accentBackground/g)) {
+      if (live[match.index] === 1) {
+        violations.push(`${rel}:${lineAt(src, match.index)} — accentBackground outside its owners`);
+      }
+    }
+  };
+  if (existsSync(PUBLIC_DIR)) {
+    for (const pkg of readdirSync(PUBLIC_DIR, { withFileTypes: true })) {
+      if (!pkg.isDirectory() || pkg.name.startsWith(".") || pkg.name === "node_modules") continue;
+      walkFiles(join(PUBLIC_DIR, pkg.name, "src"), scan);
+    }
+  }
+  for (const dir of [APPS_DIR, FEATURES_DIR, PACKAGES_DIR]) walkFiles(dir, scan);
+  return violations;
+}
+
 /**
  * Run structural convention checks over a consumer tree.
  *
@@ -1603,13 +2114,40 @@ export function runConventionChecks(options = {}) {
   const rnWebExports = checkReactNativeWebExports();
   const importMeta = checkImportMetaInPublicSource();
   const graphVars = checkGraphVarsCoverage();
+  const retiredScaleKnobs = checkRetiredScaleKnobs();
+  const overlayOwnership = checkOverlayOwnership();
+  const accentSolidOwners = checkAccentSolidOwners();
   const tokens = checkTransitionTokens();
   const styleTokens = checkStyleTokens();
   const themeNames = checkThemeNames();
   const intents = checkIntentTokens();
   const animProps = checkAnimationProps();
+  const oneSidebar = checkOneSidebar();
+  const hugContent = checkHugContent();
+  const responsiveParity = checkResponsiveParity();
   let failed = false;
 
+  for (const [rule, list] of /** @type {const} */ ([
+    [
+      "Convention (LC-101 ONE-SIDEBAR): one sidebar column per page. A page's secondary panel (filters, group-by) stacks under the shell nav through useShellSidebarPanel, and phones open it as a sheet.",
+      oneSidebar,
+    ],
+    [
+      "Convention (LC-102 HUG-CONTENT): columns and fields hug their content; no space-between / space-around / space-evenly. Pre-rule sites are the hugContent ratchet in docs/layout-rule-baselines.json.",
+      hugContent,
+    ],
+    [
+      "Convention (LC-103 RESPONSIVE-PARITY): a phone shows the same information. Content hidden on phones names its phone twin (⋯ menu, icon twin, sheet) with a `responsive-parity: <reason>` comment.",
+      responsiveParity,
+    ],
+  ])) {
+    if (!list.length) continue;
+    failed = true;
+    console.error(`${rule}\n`);
+    for (const msg of list) console.error(`  ${msg}`);
+    console.error("");
+  }
+
   if (animProps.legacyProp.length) {
     failed = true;
     console.error(
@@ -1732,6 +2270,41 @@ export function runConventionChecks(options = {}) {
     console.error("");
   }
 
+  if (accentSolidOwners.length) {
+    failed = true;
+    console.error(
+      "Convention (LC-05 ONE-EMPHASIS): the accent solid paints the primary CTA, the checked Switch track, progress fills and current/checked marks only, through `componentColors.indicator.mark` or `formSelectedColors.mark`. A selected, current or highlighted fill takes `componentColors.selection` / `formSelectionColors`; a data-identity default takes `useChartPalette().single`; accent text takes `$accentColor`.\n",
+    );
+    for (const msg of accentSolidOwners) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (overlayOwnership.shadows.length) {
+    failed = true;
+    console.error(
+      "Convention (LC-85 ONE SHADOW LADDER, check 15): spread knobProps.elevatedSurface, elevationChrome or thumbShadow instead of owning a shadow literal.\n",
+    );
+    for (const msg of overlayOwnership.shadows) console.error(`  ${msg}`);
+    console.error("");
+  }
+  if (overlayOwnership.frames.length) {
+    failed = true;
+    console.error(
+      "Convention (E-OVERLAY ONE FRAME, check 16): use the house frame from @multiplatform.one/theme or @multiplatform.one/components and let it own elevation.\n",
+    );
+    for (const msg of overlayOwnership.frames) console.error(`  ${msg}`);
+    console.error("");
+  }
+
+  if (retiredScaleKnobs.length) {
+    failed = true;
+    console.error(
+      'Convention (LC-100 TOKEN-SCALE, check 14): the size, space and density knobs are retired. Size, spacing and radius come from the preset\'s generated token scale (`Preset.scale`), and the only per-site control is Tamagui\'s own `size="$n"` (forwarded to a subtree by `<Surface size="$3">`). Drop the knob key, replace `compact` with a size token, drop `data-density` (`data-size-token` carries the token), and give `<Surface>` a `$size` key.\n',
+    );
+    for (const msg of retiredScaleKnobs) console.error(`  ${msg}`);
+    console.error("");
+  }
+
   if (importMeta.length) {
     failed = true;
     console.error(