@multiplatform.one/config 7.34.4 → 7.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/config",
-  "version": "7.34.4",
+  "version": "7.35.0",
   "description": "Shared build and test configuration presets for multiplatform.one",
   "keywords": [
     "config",
@@ -25,6 +25,9 @@
     "url": "git+https://git.corp.bitspur.com/multiplatform.one/mpo.git",
     "directory": "public/config"
   },
+  "bin": {
+    "mpo-design-lint": "./design-lint.mjs"
+  },
   "source": "src/index.ts",
   "files": [
     "src",
@@ -42,7 +45,8 @@
     "!tsconfig/dist",
     "!tsconfig/types",
     "types",
-    "!types/.tsbuildinfo"
+    "!types/.tsbuildinfo",
+    "design-lint.mjs"
   ],
   "type": "module",
   "sideEffects": false,
@@ -93,25 +97,26 @@
       "types": "./lint.d.ts",
       "default": "./lint.mjs",
       "import": "./lint.mjs"
-    }
+    },
+    "./design-lint": "./design-lint.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/utils": "^7.34.4",
+    "@multiplatform.one/utils": "^7.35.0",
     "@tamagui/vite-plugin": "2.7.6",
     "@vitejs/plugin-react": "^6.1.2",
     "dotenv": "^17.4.2",
     "fast-flow-transform": "^0.0.3",
+    "typescript": "~5.9.3",
     "vite": "^8.0.10",
     "vite-plugin-external": "^6.2.2",
     "vite-plugin-i18next-loader": "^3.1.3",
     "vitest": "^4.1.5"
   },
   "devDependencies": {
-    "tsdown": "^0.21.10",
-    "typescript": "~5.9.3"
+    "tsdown": "^0.21.10"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.20.0",
@@ -139,6 +144,7 @@
   "scripts": {
     "typecheck": "tsgo --noEmit",
     "build": "rm -rf lib types 2>/dev/null && tsc -p tsconfig.build.json && tsdown",
-    "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html"
+    "test": "pnpm test:design && vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html",
+    "test:design": "node --test design-lint.spec.mjs"
   }
 }

package/src/lint.spec.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -567,10 +567,10 @@ describe("a scaffolded project, where apps/one is renamed and public/ is pruned
   }
 
   function animationRegistry(root: string) {
-    mkdirSync(join(root, "public", "theme", "src", "theme", "animations"), { recursive: true });
+    mkdirSync(join(root, "public", "theme", "src", "theme"), { recursive: true });
     writeFileSync(
-      join(root, "public", "theme", "src", "theme", "animations", "css.ts"),
-      'export const animationConfig = {\n  medium: "ease-in 300ms",\n} as const;\n',
+      join(root, "public", "theme", "src", "theme", "motionTiming.ts"),
+      'export const animationConfig = {\n  medium: "300ms ease-out",\n  "100ms": "100ms ease-out",\n  quickest: "80ms ease-out",\n} as const;\n',
     );
   }
 
@@ -613,6 +613,13 @@ describe("a scaffolded project, where apps/one is renamed and public/ is pruned
     expect(errors).toMatch(/apps\/demo\/App\.tsx:1 — transition="mediun"/);
   });
 
+  it.each(["100ms", "quickest", "ease"])("validates v5 transition %s", (token) => {
+    const root = makeTree();
+    animationRegistry(root);
+    writeFileSync(join(root, "apps", "demo", "App.tsx"), `<View transition="${token}" />;\n`);
+    expect(run(root).code).toBe(token === "ease" ? 1 : 0);
+  });
+
   it("passes a registered transition when the registry is readable", () => {
     const root = makeTree();
     animationRegistry(root);
@@ -915,7 +922,7 @@ describe("LC-24 enter/exit driver (MPO-327)", () => {
     const root = makeTree();
     writeFileSync(
       join(root, "apps", "demo", "App.tsx"),
-      "export const App = () => <View enterStyle={{ opacity: 0 }} {...transitionProps(knobProps.transition)} />;\n",
+      "export const App = () => <View enterStyle={{ opacity: 0 }} {...transitionProps(knobProps.motion.overlay)} />;\n",
     );
     const { code, errors } = run(root);
     expect(errors).not.toMatch(/LC-24/);
@@ -1043,3 +1050,502 @@ ${csfTail}`,
     expect(run(root).code).toBe(0);
   });
 });
+
+describe("retired scale knobs (LC-100 TOKEN-SCALE, check 14)", () => {
+  // Built, not written: scripts/mr-job-inputs reads a literal package import in
+  // any file, fixtures included, as a workspace dependency of this package.
+  const house = "@multiplatform.one";
+
+  function run(root: string) {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const code = runConventionChecks({ roots: { root } });
+    const messages = error.mock.calls.map((call) => String(call[0])).join("\n");
+    error.mockRestore();
+    log.mockRestore();
+    warn.mockRestore();
+    return { code, messages };
+  }
+
+  function source(root: string, rel: string, body: string) {
+    const full = join(root, rel);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, body);
+    return rel;
+  }
+
+  it("fails a planted density knob in <Preset overrides>, naming file and line", () => {
+    const root = makeTree();
+    const file = source(
+      root,
+      "features/demo/Dense.tsx",
+      `import { Preset } from "${house}/theme";
+export const Dense = () => (
+  <Preset overrides={{ borderRadius: "full", density: "compact" }}>{null}</Preset>
+);
+`,
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain("LC-100 TOKEN-SCALE");
+    expect(messages).toContain(`${file}:3 — \`density\` knob in a knob literal`);
+  });
+
+  it("fails size and space keys in a preset's knobs, its state knobs and a typed literal", () => {
+    const root = makeTree();
+    const file = source(
+      root,
+      "public/theme/src/theme/presets.ts",
+      `import type { Knobs, Preset } from "./knobs";
+export const roomy: Preset = {
+  theme: "light",
+  knobs: {
+    borderRadius: "medium",
+    space: "large",
+    hover: { size: "small" },
+  },
+  intents: {},
+  tints: [],
+};
+export const loose: Partial<Knobs> = { size: "large" };
+`,
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain(`${file}:6 — \`space\` knob in a knob literal`);
+    expect(messages).toContain(`${file}:7 — \`size\` knob in a knob literal`);
+    expect(messages).toContain(`${file}:12 — \`size\` knob in a knob literal`);
+  });
+
+  it("fails a compact prop on a house Button and a word size on <Surface>", () => {
+    const root = makeTree();
+    const app = source(
+      root,
+      "apps/demo/Toolbar.tsx",
+      `import { Button } from "${house}/forms";
+import { Surface } from "${house}/theme";
+export const Toolbar = () => (
+  <Surface size="small">
+    <Button compact onPress={() => {}}>Save</Button>
+  </Surface>
+);
+`,
+    );
+    const catalog = source(
+      root,
+      "public/components/src/Bar.tsx",
+      `export const Bar = () => <Surface density="compact"><Chip compact={true} /></Surface>;
+`,
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain(`${app}:4 — \`<Surface size="small">\``);
+    expect(messages).toContain(`${app}:5 — \`compact\` on <Button>`);
+    expect(messages).toContain(`${catalog}:1 — \`<Surface density>\``);
+    expect(messages).toContain(`${catalog}:1 — \`compact\` on <Chip>`);
+  });
+
+  it("fails a data-density attribute and a density value outside a knob literal", () => {
+    const root = makeTree();
+    const file = source(
+      root,
+      "public/forms/src/Field.tsx",
+      `const attrs = { "data-density": "compact" };
+export const mode = { density: "comfortable" };
+export const Field = () => <div data-density="compact" {...attrs} />;
+`,
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain(`${file}:1 — \`data-density\` attribute`);
+    expect(messages).toContain(`${file}:2 — \`density: "comfortable"\``);
+    expect(messages).toContain(`${file}:3 — \`data-density\` attribute`);
+  });
+
+  it("passes size tokens, an app's own compact prop, comments, strings and specs", () => {
+    const root = makeTree();
+    source(
+      root,
+      "apps/demo/Panel.tsx",
+      `import { Button } from "${house}/forms";
+import { Surface } from "${house}/theme";
+function Local({ compact }: { compact?: boolean }) {
+  return compact ? null : <Button size="$3">Go</Button>;
+}
+export const Panel = () => (
+  <Surface size="$3">
+    <Local
+      // the old compact prop is gone; density: "compact" lives in history
+      compact
+    />
+    <Button size={"$3"}>{"density: compact"}</Button>
+  </Surface>
+);
+`,
+    );
+    source(
+      root,
+      "public/theme/src/theme/cookies.spec.ts",
+      `export const stale = { density: "compact", size: "small", "data-density": 1 };
+`,
+    );
+    expect(run(root).code).toBe(0);
+  });
+});
+
+describe("the v5 theme registry", () => {
+  it("accepts built v5 children and rejects retired v4 names and keys", () => {
+    const root = makeTree();
+    symlinkSync(join(process.cwd(), "../../node_modules"), join(root, "node_modules"), "dir");
+    const app = join(root, "apps/demo/App.tsx");
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      writeFileSync(
+        app,
+        'export const App = () => <View theme="gray"><View theme="purple" color="$neutral9" /><View theme="SliderActive" color="$teal9" backgroundColor="$backgroundPress" borderColor="$borderColor" /><View theme="active" color="$color0" /><View theme="alt1" color="$accentColor" /><View color="$syntaxBlue" /><View color="$colorTransparent" /></View>;',
+      );
+      expect(runConventionChecks({ roots: { root } })).toBe(0);
+      writeFileSync(
+        app,
+        'export const App = () => <View theme="SwitchThumb"><View theme="mauve" /><View theme="teal" /><View theme="neutral" /><View theme="surface1" color="$amber9" /><View backgroundColor="$backgroundStrong" /><View backgroundColor="$backgroundTransparent" /><View color="$colorTransparent" /></View>;',
+      );
+      expect(runConventionChecks({ roots: { root } })).toBe(1);
+      const errors = error.mock.calls.flat().join("\n");
+      expect(errors).toContain('theme="SwitchThumb"');
+      expect(errors).toContain('theme="mauve"');
+      expect(errors).toContain('theme="teal"');
+      expect(errors).toContain('theme="neutral"');
+      expect(errors).toContain('theme="surface1"');
+      for (const key of ["amber9", "backgroundStrong", "backgroundTransparent"]) {
+        expect(errors).toContain(`$${key}`);
+      }
+    } finally {
+      error.mockRestore();
+      log.mockRestore();
+      warn.mockRestore();
+    }
+  });
+});
+
+describe("layout rules (LC-101 ONE-SIDEBAR, LC-102 HUG-CONTENT, LC-103 RESPONSIVE-PARITY)", () => {
+  function run(root: string) {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const code = runConventionChecks({ roots: { root } });
+    const messages = error.mock.calls.map((call) => String(call[0])).join("\n");
+    error.mockRestore();
+    log.mockRestore();
+    warn.mockRestore();
+    return { code, messages };
+  }
+
+  function layoutTree(baselines: {
+    secondSidebar?: string[];
+    hugContent?: Record<string, number>;
+  }) {
+    const root = makeTree();
+    mkdirSync(join(root, "docs"), { recursive: true });
+    writeFileSync(
+      join(root, "docs", "layout-rule-baselines.json"),
+      JSON.stringify({ secondSidebar: [], hugContent: {}, ...baselines }),
+    );
+    return root;
+  }
+
+  const write = (root: string, rel: string, src: string) => {
+    const path = join(root, rel);
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, src);
+  };
+
+  it("fails a page that renders its own sidebar column beside the shell nav", () => {
+    const root = layoutTree({});
+    write(
+      root,
+      "features/demo/List.tsx",
+      "export const L = () => <XStack><FacetSidebar /><Rows /></XStack>;\n",
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain("LC-101");
+    expect(messages).toContain("features/demo/List.tsx:1 — <FacetSidebar>");
+  });
+
+  it("passes a page that hands its panel to the shell, a shell, and a sidebar's own file", () => {
+    const root = layoutTree({});
+    write(
+      root,
+      "features/demo/List.tsx",
+      "export const L = () => { useShellSidebarPanel({ title: 'x', content: <FacetSidebar fill /> }); return null; };\n",
+    );
+    write(root, "features/demo/AppShell.tsx", "export const S = () => <NavSidebar />;\n");
+    write(root, "features/demo/FacetSidebar.tsx", "export const F = () => <InnerSidebar />;\n");
+    write(root, "features/demo/Notes.tsx", "// <OldSidebar /> was removed\nexport const N = 1;\n");
+    expect(run(root).code).toBe(0);
+  });
+
+  it("holds pre-rule sidebar sites to the baseline and fails a stale row", () => {
+    const root = layoutTree({
+      secondSidebar: ["features/demo/Form.tsx", "features/demo/Gone.tsx"],
+    });
+    write(root, "features/demo/Form.tsx", "export const F = () => <FormSidebar />;\n");
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).not.toContain("features/demo/Form.tsx:1");
+    expect(messages).toContain("features/demo/Gone.tsx — secondSidebar baseline row has no site");
+  });
+
+  it("ratchets spread justification: over the baseline fails, under it asks to lower the row", () => {
+    const root = layoutTree({
+      hugContent: { "features/demo/Row.tsx": 1, "features/demo/Low.tsx": 2 },
+    });
+    write(
+      root,
+      "features/demo/Row.tsx",
+      'export const R = () => <><XStack justifyContent="space-between" /><XStack justifyContent="space-around" /></>;\n',
+    );
+    write(root, "features/demo/Low.tsx", 'export const s = { justifyContent: "space-between" };\n');
+    write(
+      root,
+      "features/demo/Fine.tsx",
+      '// justifyContent="space-between" in a comment is not a layout\nexport const F = () => <XStack gap="$2" />;\n',
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain(
+      'features/demo/Row.tsx:1 — justifyContent="space-around" (2 in file, baseline 1)',
+    );
+    expect(messages).toContain("features/demo/Low.tsx — 1 spread justifications, baseline says 2");
+    expect(messages).not.toContain("Fine.tsx");
+  });
+
+  it("fails content hidden on phones unless it names its phone twin", () => {
+    const root = layoutTree({});
+    write(
+      root,
+      "features/demo/Toolbar.tsx",
+      [
+        "export const T = () => (",
+        "  <XStack>",
+        '    <Button $max-sm={{ display: "none" }}>Export</Button>',
+        '    <Chip display="none" $md={{ display: "flex" }}>Draft</Chip>',
+        "    {/* responsive-parity: the ⋯ menu carries Print on phones */}",
+        '    <Button $max-sm={{ display: "none" }}>Print</Button>',
+        '    <Spacer display="none" />',
+        "  </XStack>",
+        ");",
+        "",
+      ].join("\n"),
+    );
+    const { code, messages } = run(root);
+    expect(code).toBe(1);
+    expect(messages).toContain("features/demo/Toolbar.tsx:3 — hidden on phones");
+    expect(messages).toContain("features/demo/Toolbar.tsx:4 — hidden on phones");
+    expect(messages).not.toContain("Toolbar.tsx:6");
+    expect(messages).not.toContain("Toolbar.tsx:7");
+  });
+
+  it("skips every layout check in a project without the baselines (docs/ pruned)", () => {
+    const root = makeTree();
+    write(
+      root,
+      "features/demo/List.tsx",
+      'export const L = () => <XStack justifyContent="space-between"><FacetSidebar /></XStack>;\n',
+    );
+    expect(run(root).code).toBe(0);
+  });
+});
+
+function runOverlayChecks(file: string, body: string) {
+  const root = makeTree();
+  const full = join(root, file);
+  if (file.startsWith("apps/"))
+    mkdirSync(join(root, "features", file.split("/")[1]), { recursive: true });
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, body);
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  try {
+    const code = runConventionChecks({ roots: { root } });
+    return { code, messages: error.mock.calls.map((call) => String(call[0])).join("\n") };
+  } finally {
+    error.mockRestore();
+    log.mockRestore();
+    warn.mockRestore();
+  }
+}
+
+describe("one shadow ladder (LC-85 ONE SHADOW LADDER, check 15)", () => {
+  it.each([
+    ["public/forms/src/Panel.tsx", 'const style = { boxShadow: "0 1px 2px rgba(0,0,0,0.2)" };', 1],
+    [
+      "features/demo/Panel.tsx",
+      'const S = "0px 8px 28px rgba(0,0,0,0.12)";\nexport const Panel = () => <View style={{ boxShadow: S }} />;',
+      2,
+    ],
+    [
+      "packages/demo/Panel.tsx",
+      "export const Panel = () => <View boxShadow={`0 0 2px ${color}`} />;",
+      1,
+    ],
+    ["features/demo/Panel.tsx", 'export const Panel = () => <View boxShadow="0 0 red" />;', 1],
+    [
+      "features/demo/Panel.tsx",
+      'const shadow: string = "0 1px 2px black";\nexport const Panel = () => <View style={{ boxShadow: shadow }} />;',
+      2,
+    ],
+  ])("rejects owned shadows in %s", (file, body, line) => {
+    const result = runOverlayChecks(file, body);
+    expect(result.code).toBe(1);
+    expect(result.messages).toContain("check 15");
+    expect(result.messages).toContain(`${file}:${line}`);
+  });
+  it.each([
+    ["public/forms/src/Panel.tsx", 'const style = { boxShadow: "none" };'],
+    ["features/demo/Panel.tsx", 'const style = { boxShadow: "" };'],
+    ["features/demo/Panel.tsx", "const style = { boxShadow: chrome.shadow };"],
+    ["features/demo/Panel.tsx", "const style = { boxShadow: resolveShadow() };"],
+    [
+      "public/connectkit/src/Panel.tsx",
+      'const style = { boxShadow: "0 1px 2px rgba(0,0,0,0.2)" };',
+    ],
+    [
+      "public/web3/src/connectkit/Panel.tsx",
+      'const style = { boxShadow: "0 1px 2px rgba(0,0,0,0.2)" };',
+    ],
+    [
+      "public/theme/src/theme/resolveKnobs.ts",
+      'const style = { boxShadow: "0 1px 2px rgba(0,0,0,0.2)" };',
+    ],
+    [
+      "apps/one/webext/content_scripts/Panel.tsx",
+      'const style = { boxShadow: "0 1px 2px rgba(0,0,0,0.2)" };',
+    ],
+    ["features/demo/Panel.spec.tsx", 'const style = { boxShadow: "0 1px 2px rgba(0,0,0,0.2)" };'],
+    ["features/demo/Panel.tsx", '// boxShadow: "0 1px 2px rgba(0,0,0,0.2)"'],
+  ])("allows recipe paint and explicit exemptions in %s", (file, body) => {
+    const result = runOverlayChecks(file, body);
+    expect(result.code).toBe(0);
+    expect(result.messages).not.toContain("check 15");
+  });
+});
+
+describe("one overlay frame (E-OVERLAY ONE FRAME, check 16)", () => {
+  it.each([
+    "export const Panel = () => <Popover.Content />;",
+    "export const Panel = () => <Dialog.Content />;",
+    "export const Panel = () => <AlertDialog.Content />;",
+    "export const Panel = () => <DialogContent elevation={knobProps.elevation} />;",
+    "export const Panel = () => <Sheet.Frame elevation={knobProps.overlayElevation} />;",
+    "export const Panel = () => <TooltipContent elevation={open ? knobProps.elevation : undefined} />;",
+  ])("rejects %s", (body) => {
+    const file = "features/demo/Panel.tsx";
+    const result = runOverlayChecks(file, body);
+    expect(result.code).toBe(1);
+    expect(result.messages).toContain("check 16");
+    expect(result.messages).toContain(`${file}:1`);
+  });
+  it.each([
+    ["features/demo/Panel.tsx", "export const Panel = () => <PopoverContent />;"],
+    [
+      "public/theme/src/theme/overlaySurfaces.tsx",
+      "export const Panel = () => <Popover.Content />;",
+    ],
+    ["features/demo/Panel.tsx", "// <Popover.Content />"],
+    ["features/demo/Panel.spec.tsx", "export const Panel = () => <Popover.Content />;"],
+  ])("allows the shared frame in %s", (file, body) => {
+    const result = runOverlayChecks(file, body);
+    expect(result.code).toBe(0);
+  });
+});
+
+describe("accent solid owners (LC-05 ONE-EMPHASIS)", () => {
+  function run(source: string, file = "public/components/src/Selected.tsx") {
+    const root = makeTree();
+    const full = join(root, file);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, source);
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const code = runConventionChecks({ roots: { root } });
+    const messages = error.mock.calls.map((call) => String(call[0])).join("\n");
+    error.mockRestore();
+    log.mockRestore();
+    warn.mockRestore();
+    return { code, messages };
+  }
+
+  it.each([
+    'export const Selected = () => <View backgroundColor="$accentBackground" />;',
+    "export const fill = theme.accentBackground?.val;",
+  ])("fails an accent solid in a component: %s", (source) => {
+    const { code, messages } = run(source);
+    expect(code).toBe(1);
+    expect(messages).toContain("LC-05 ONE-EMPHASIS");
+    expect(messages).toContain("public/components/src/Selected.tsx:1");
+  });
+
+  it.each(["apps/demo", "features/demo", "packages/ui/src"])(
+    "scans %s as well as published sources",
+    (dir) => {
+      expect(run('export const fill = "$accentBackground";', `${dir}/fill.mjs`).code).toBe(1);
+    },
+  );
+
+  it.each([
+    "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",
+  ])("allows the owner %s", (file) => {
+    expect(run("export const fill = theme.accentBackground?.val;", file).code).toBe(0);
+  });
+
+  it("keeps strings containing comment delimiters", () => {
+    const { code, messages } = run(`const url = "https://example.invalid";
+const literal = "/* $accentBackground */";
+const value = "// $accentBackground";`);
+    expect(code).toBe(1);
+    expect(messages).toContain("public/components/src/Selected.tsx:2");
+    expect(messages).toContain("public/components/src/Selected.tsx:3");
+  });
+
+  it("ignores line, block and JSX comments", () => {
+    expect(
+      run(`// backgroundColor="$accentBackground"
+/* theme.accentBackground */
+export const Selected = () => <View>{/* "$accentBackground" */}</View>;`).code,
+    ).toBe(0);
+  });
+
+  it("ends a quote at the line break, so a JSX apostrophe cannot open a comment", () => {
+    expect(
+      run(`export const Hint = () => <Text>Don't pick</Text>;
+// backgroundColor="$accentBackground"
+export const Other = () => <Text>It's fine</Text>;`).code,
+    ).toBe(0);
+  });
+
+  it.each(["stories.tsx", "spec.tsx", "test.tsx", "d.ts"])("ignores %s", (suffix) => {
+    expect(
+      run(
+        'const fill = "$accentBackground"; const meta = {};\nexport default meta;',
+        `public/components/src/Selected.${suffix}`,
+      ).code,
+    ).toBe(0);
+  });
+
+  it("reports every live occurrence with its line", () => {
+    const { messages } = run(`const fill = "$accentBackground";
+const value = theme.accentBackground;`);
+    expect(messages).toContain("public/components/src/Selected.tsx:1");
+    expect(messages).toContain("public/components/src/Selected.tsx:2");
+  });
+});

package/src/phosphorTokenColor.spec.ts

@@ -38,7 +38,7 @@ describe("phosphorTokenColorPlugin", () => {
     const fromIcon = resolveId("../lib/IconBase.es.js", `${dist}/csr/Heart.es.js`);
     const fromBarrel = resolveId("./lib/IconBase.es.js", `${dist}/index.es.js?v=1a2b`);
     expect(fromIcon?.startsWith("\0mpo-phosphor-token-icon-base:")).toBe(true);
-    expect(fromIcon?.endsWith(iconBase)).toBe(true);
+    expect(fromIcon?.endsWith(`${iconBase}?mpo-token-icon`)).toBe(true);
     expect(fromBarrel).toBe(fromIcon);
   });
 
@@ -49,6 +49,12 @@ describe("phosphorTokenColorPlugin", () => {
     expect(resolveId(iconBase, wrapper)).toBeNull();
   });
 
+  it("keeps virtual modules out of file-only Flow loaders", () => {
+    const wrapper = resolveId("../lib/IconBase.es.js", `${dist}/csr/Heart.es.js`) ?? "";
+    expect(wrapper).not.toMatch(/\.(flow|jsx?)$/);
+    expect(load(wrapper)).toContain(`import IconBase from ${JSON.stringify(iconBase)}`);
+  });
+
   it("loads a wrapper that resolves tokens through the theme and renders the original", () => {
     const wrapper = resolveId("../lib/IconBase.es.js", `${dist}/csr/Heart.es.js`) ?? "";
     const code = load(wrapper) ?? "";

package/src/phosphorTokenColor.ts

@@ -4,6 +4,7 @@ import { pathToFileURL } from "node:url";
 import type { Plugin } from "vite";
 
 const virtualPrefix = "\0mpo-phosphor-token-icon-base:";
+const virtualSuffix = "?mpo-token-icon";
 const iconBaseFilter = /IconBase\.es\.js$/;
 const phosphorLibFile = /\/@phosphor-icons\/react\/dist\/lib\/IconBase\.es\.js$/;
 const phosphorBarrelFile = /\/@phosphor-icons\/react\/dist\/index\.es\.js$/;
@@ -59,12 +60,12 @@ function resolvePhosphorIconBase(id: string, importer: string | undefined): stri
   const importerPath = toPosix(importer);
   if (!importerPath.includes("/@phosphor-icons/react/dist/")) return null;
   const target = toPosix(id.startsWith(".") ? path.resolve(path.dirname(importer), id) : id);
-  return phosphorLibFile.test(target) ? virtualPrefix + target : null;
+  return phosphorLibFile.test(target) ? virtualPrefix + target + virtualSuffix : null;
 }
 
 function loadTokenColorIconBase(id: string): string | null {
   return id.startsWith(virtualPrefix)
-    ? tokenColorIconBaseSource(id.slice(virtualPrefix.length))
+    ? tokenColorIconBaseSource(id.slice(virtualPrefix.length, -virtualSuffix.length))
     : null;
 }
 

package/src/storybook.spec.ts

@@ -15,6 +15,13 @@ describe("createStorybookViteConfig", () => {
     expect(include).toContain("d3-scale");
   });
 
+  it("aliases an exported subpath whose name is not its path to the export's source file", () => {
+    const alias = config.resolve?.alias as Record<string, string>;
+    expect(alias["@multiplatform.one/theme/scale-attribute"]).toMatch(
+      /public\/theme\/src\/theme\/scale\/scaleAttribute\.ts$/,
+    );
+  });
+
   it("pre-includes i18next so its late discovery cannot re-optimize", () => {
     expect(include).toContain("i18next");
     expect(include).toContain("react-i18next");