@yschimke/compose-design-map 0.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,110 @@
+# @yschimke/compose-design-map
+
+`design-map.json` is [design-parity](https://github.com/yschimke/design-parity)'s correspondence
+file: it says which design node a code component is meant to look like. This package **writes**
+one, from the catalog annotations [compose-ai-tools](https://github.com/yschimke/compose-ai-tools)
+defines.
+
+```
+./gradlew :<module>:composePreviewDiscover
+npx --yes @yschimke/compose-design-map \
+  --previews <module>/build/compose-previews/previews.json
+```
+
+Dependency-free and Node-only, so `npx` is the whole install. Both outputs are generated —
+regenerate rather than edit. `--check` regenerates in memory and exits non-zero if a committed copy
+has drifted, which is the CI posture.
+
+Pin the version in CI. Both files are committed and checked, so the projection's version is an
+input to a checked-in artifact: float it, and a release here turns a downstream repo red for a
+change nobody there made.
+
+## Why the producer lives here
+
+Every field the projection reads is defined in this repository:
+
+| Field on `previews.json` | Declared by |
+| --- | --- |
+| `catalog.reference`, `referenceSet`, `noReference`, `referenceContentsOnly` | [`@CatalogComponent`](https://github.com/yschimke/compose-ai-tools/blob/main/api/preview-annotations/src/commonMain/kotlin/ee/schimke/composeai/preview/CatalogComponent.kt) |
+| `catalog.props`, `catalog.state` | `@CatalogVariant` |
+| `overrides.seeds`, `overrides.props` | `@OverrideVariant` / `@PreviewAxis` |
+
+Rename one of those and the projection has to change in the same commit. Keeping the two on
+opposite sides of a repo boundary is how a manifest reader goes quietly stale — and the reference
+belongs on the annotation rather than in a JSON map for the same reason: a map keyed on preview
+names drifts the moment a preview is renamed, and fails silently when it does.
+
+The consuming half already lived here too — [`design-references.mjs`](https://github.com/yschimke/compose-ai-tools/blob/main/scripts/design-artifacts/design-references.mjs)
+reads a `design-map.json` to build a published catalog's `references/index.json`. Until now nothing
+in the ecosystem wrote one except a hand-maintained script in a downstream catalog repo.
+
+## Where the split falls
+
+A catalog picturing `Button` at three sizes and two shapes has six renders and **one** reference.
+Pairing the other five means answering "which kit node is `size=l`?" — and that is not a question
+this repo can answer:
+
+```
+  previews.json
+      │
+      │  compose-design-map            ← THIS PACKAGE. Knows what the annotations mean.
+      │
+      ├──▶ design-map.json             base references, one per component. Valid on its own.
+      │
+      └──▶ design-map-variants.json    "these previews are the same component with these knobs
+                                        turned" — unresolved, because `size=l` is a fact about
+                                        the Compose API and `Size=Large` is a fact about somebody's
+                                        design kit
+                │
+                │  @design-parity/kit-index      ← THE OTHER REPO. Knows what the KIT means.
+                ▼
+           design-map.json with a tagged ref/previewId pair per variant
+```
+
+`size=l` → `Size=Large` is a translation against a kit's published vocabulary. That vocabulary is a
+Figma concern, it needs a Figma credential to derive, and it differs per kit — none of which this
+repo has any business holding. So the variant renders come out as **declarations** and a resolver
+that owns a kit index turns them into node ids.
+
+The two halves are separable because the first is useful alone: a repo with no kit index still gets
+a valid map of base references, which is most of the value at none of the cost.
+
+## The sidecar
+
+`design-map-variants.json` carries `schema: "compose-preview-design-map-variants/v1"`; a resolver
+must match that string before reading it. One entry per component that has variant renders:
+
+```jsonc
+{
+  "schema": "compose-preview-design-map-variants/v1",
+  "components": [
+    {
+      "code": "catalog/Catalog.kt#FilledButton",   // the design-map entry these belong to
+      "componentId": "Button/Filled",
+      "reference": "figma:AbCdEf/1:2",              // the node a resolver walks from
+      "basePreviewId": "…FilledButton_Light",
+      "renders": [
+        { "previewId": "…FilledButton_Light_VARIANT_l", "name": "l",
+          "seeds": [{ "key": "size", "raw": "l" }, { "key": "shape", "raw": "round" }] }
+      ]
+    }
+  ]
+}
+```
+
+It is a separate file rather than another key on the map because the design-map schema sets
+`additionalProperties: false` — a map carrying an extra key would fail its own validator. No file is
+written when nothing declares an axis.
+
+## Two things worth knowing
+
+**Only the light capture is mapped.** One entry per component, not per rendered mode, and the light
+one — because that is the mode design kits draw their frames in. Diffing a dark render against a
+light reference reports the whole palette as a finding.
+
+**`overrides.props` beats `overrides.seeds` where both exist.** They are not the same list. `seeds`
+holds only the values that differ from the composable's defaults; `props` — emitted for a
+`@PreviewAxis` cross product — carries the full axis assignment, defaults included. A cell that
+knows its own axes pairs by construction, which is exactly what `OverrideVariantSpec.props` was
+added for. A cell described only by its non-default seeds is missing the axes it happens to sit at,
+and a kit that spells its default size explicitly in a combination cell then has nothing to match.

package/design-map.mjs

@@ -0,0 +1,259 @@
+/**
+ * Project a discovery manifest into a `design-map.json` — the correspondence file design-parity
+ * reads to know which design node a code component is meant to look like.
+ *
+ * ## Why this is a projection and not a config file
+ *
+ * design-parity joins a code subject to a design reference through a `design-map.json` entry:
+ * `{ code, source, ref, previewId }`. Hand-maintaining that for a catalog's worth of previews is
+ * exactly the mapping-config sprawl a catalog exists to avoid — and it drifts the moment a preview
+ * is renamed, silently, because the join keys on the fully-qualified preview id.
+ *
+ * So the map is DERIVED. Every catalogued component already carries its seed-kit handle on the
+ * annotation this repo defines:
+ *
+ *     @CatalogComponent(id = "Button/Filled", reference = "figma:<fileKey>/<nodeId>")
+ *
+ * `composePreviewDiscover` writes that through to `previews.json` as `catalog.reference`, so this
+ * module is a pure projection of the annotations. Keeping the ref in code is the point: a JSON map
+ * keyed on preview names drifts when a preview is renamed, and fails silently when it does.
+ *
+ * ## Why this lives HERE and not in design-parity
+ *
+ * Every field it reads — `catalog.reference`, `referenceSet`, `noReference`,
+ * `referenceContentsOnly`, `catalog.props`, `overrides.seeds` — is defined in this repository, by
+ * `@CatalogComponent` / `@CatalogVariant` / `@OverrideVariant` and emitted by this repository's
+ * discovery. Rename a field and the projection has to change in the same commit; putting the two
+ * on opposite sides of a repo boundary is how a manifest reader goes quietly stale.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not resolve a variant knob to a design node. `size=l` is a fact about the Compose API;
+ * `Size=Large` is a fact about somebody's design kit, and translating between them needs that kit's
+ * published vocabulary — which this repo has no business holding, and which
+ * [`@design-parity/kit-index`](https://github.com/yschimke/design-parity/tree/main/packages/kit-index)
+ * does hold.
+ *
+ * So the variant renders come out as **declarations**, in a sidecar
+ * ({@link DESIGN_MAP_VARIANTS_SCHEMA}): "this preview is the same component with these knobs
+ * turned". A resolver that owns a kit index turns each into a tagged `ref`/`previewId` pair beside
+ * the base one. A repo with no kit index still gets a valid map of base references, which is the
+ * majority of the value and costs no design-tool credential.
+ *
+ * The sidecar is a separate file rather than another key on the map because the design-map schema
+ * sets `additionalProperties: false` — a map carrying an extra key would fail its own validator.
+ *
+ * Pure and dependency-free (no `@design-parity/*`, no I/O) so it unit-tests without an `npm ci`,
+ * like its siblings `catalog-image-path.mjs` / `catalog-variants.mjs`. The I/O around it is
+ * `emit-design-map.mjs`.
+ */
+
+/** The sidecar `schema` string a resolver must match before reading variant declarations. */
+export const DESIGN_MAP_VARIANTS_SCHEMA = "compose-preview-design-map-variants/v1";
+
+/**
+ * The capture a component's base reference pairs with.
+ *
+ * One entry per component, not per rendered mode — and the LIGHT capture, because that is the mode
+ * design kits draw their frames in. Diffing a dark render against a light reference reports the
+ * whole palette as a finding.
+ */
+const LIGHT_CAPTURE = /_Light$/;
+
+/** A light capture that is also an `@OverrideVariant` render: `…_Light_VARIANT_<name>`. */
+const LIGHT_VARIANT_CAPTURE = /_Light_VARIANT_/;
+
+/** design-parity addresses a code subject as `<path>#<function>`. */
+export function codeHandle(preview, { prefix = "catalog" } = {}) {
+  const path = preview.sourceFile ? `${prefix}/${preview.sourceFile}` : prefix;
+  return `${path}#${preview.functionName}`;
+}
+
+/**
+ * The design source a reference handle names. design-parity dispatches its adapter on this, so a
+ * wrong answer picks a driver that cannot read the ref at all.
+ */
+export function sourceForRef(ref) {
+  const scheme = String(ref).split(":")[0];
+  return scheme === "figma" ? "figma" : "claude-design";
+}
+
+/**
+ * The knobs one variant render turns, normalised to `{ key, raw }`.
+ *
+ * A variant reaches us two ways and both NAME their axis — nothing is inferred from a function
+ * name:
+ *
+ *   `@OverrideVariant(name = "l", strings = ["size=l"])` — a reseeded render of the same
+ *     composable. Arrives as role COMPONENT with `_VARIANT_` in the id and the knobs on
+ *     `overrides`.
+ *
+ *   `@CatalogVariant(of = "Fab/Standard", props = ["size=large"])` — its own composable, because
+ *     the difference is more than a knob. Arrives as role VARIANT with the knobs in `catalog.props`.
+ *
+ * For the first form, `overrides.props` is preferred over `overrides.seeds` when present. They are
+ * not the same list: `seeds` holds only the values that differ from the composable's defaults,
+ * while `props` — emitted for a `@PreviewAxis` cross product — carries the FULL axis assignment,
+ * defaults included. A cell that knows its own axes pairs by construction; one described only by
+ * its non-default seeds is missing the axes it happens to sit at, and a kit that spells its default
+ * size explicitly in a combination cell then has nothing to match against.
+ */
+export function variantSeeds(preview) {
+  const catalog = preview.catalog;
+  if (catalog?.role === "VARIANT") {
+    // `props` names the axis; `state` is the annotation's shorthand for the one axis common enough
+    // to have its own parameter. Either is a declaration, so neither is inferred —
+    // `@CatalogVariant(state = "disabled")` says the state axis as plainly as
+    // `props = ["state=disabled"]` would.
+    const props = [...(catalog.props ?? [])];
+    if (catalog.state && !props.some((p) => p.key === "state")) {
+      props.push({ key: "state", value: catalog.state });
+    }
+    return props.map((p) => ({ key: p.key, raw: p.value }));
+  }
+
+  const overrides = preview.overrides;
+  if (!overrides) return [];
+
+  const seeds = overrides.props?.length
+    ? overrides.props.map((p) => ({ key: p.key, raw: p.value }))
+    : (overrides.seeds ?? []).map((s) => ({ key: s.key, raw: s.raw }));
+
+  // An interaction variant seeds no knob — the renderer drives real hover, focus or press against
+  // the composed node instead, so the difference lives in the harness rather than in the data.
+  // A design kit models it as a value of the same `State` axis that carries Enabled and Disabled,
+  // so it enters resolution as a seed of the `state` knob and reaches the kit through the alias
+  // that knob already has. Without this the variant declares nothing: `seeds` is empty, an empty
+  // vector matches every sibling, and the render is dropped as "names no axis".
+  const interaction = overrides.interaction;
+  if (interaction && interaction !== "None" && !seeds.some((s) => s.key === "state")) {
+    seeds.push({ key: "state", raw: String(interaction).toLowerCase() });
+  }
+  return seeds;
+}
+
+/** The name a variant render goes by, for a report and for the design-map `state` slot. */
+function variantName(preview, seeds) {
+  const catalog = preview.catalog;
+  if (catalog?.role === "VARIANT") {
+    return catalog.state ?? seeds.map((s) => s.raw).join("-");
+  }
+  return preview.overrides?.name ?? seeds.map((s) => `${s.key}=${s.raw}`).join(", ");
+}
+
+/**
+ * Every variant render, grouped by the component it folds under.
+ *
+ * Both annotation forms are collected. The `@CatalogVariant` form was invisible to the first cut of
+ * this projection, which is why a FAB size axis read as unauthored while `FabSmall`/`FabMedium`/
+ * `FabLarge` sat in the catalog all along.
+ */
+export function variantRendersByComponent(previews) {
+  const byComponent = new Map();
+  for (const preview of previews) {
+    const catalog = preview.catalog;
+    if (!catalog) continue;
+
+    // An `@OverrideVariant` render is a reseed of the SAME composable, so it keeps the parent's
+    // COMPONENT role and is distinguished only by the `_VARIANT_` tag discovery puts in its id.
+    // A `@CatalogVariant` render is its own composable, so it carries the VARIANT role and an
+    // ordinary light-capture id. Either way only the light capture participates.
+    const isOverrideVariant =
+      catalog.role === "COMPONENT" && LIGHT_VARIANT_CAPTURE.test(preview.id);
+    const isCatalogVariant = catalog.role === "VARIANT" && LIGHT_CAPTURE.test(preview.id);
+    if (!isOverrideVariant && !isCatalogVariant) continue;
+
+    // A variant that names no axis says only "this is different", which is not enough to look
+    // anything up in a kit. Dropped rather than guessed at from the function name.
+    const seeds = variantSeeds(preview);
+    if (!seeds.length) continue;
+
+    const list = byComponent.get(catalog.componentId) ?? [];
+    list.push({ previewId: preview.id, name: variantName(preview, seeds), seeds });
+    byComponent.set(catalog.componentId, list);
+  }
+  return byComponent;
+}
+
+/**
+ * Project a discovery manifest into a design map plus its unresolved variant declarations.
+ *
+ * @param {Array<object>} previews `previews.json`'s `previews` array.
+ * @param {{prefix?: string}} [opts] `prefix` is the path segment prepended to each `sourceFile` to
+ *   form the code handle — the module the previews live in, as a reviewer would name it.
+ * @returns {{map: object, variants: object, diagnostics: object}} the map, the sidecar, and what
+ *   was skipped and why. Nothing is thrown for a missing reference: an unmapped component is a
+ *   fact to report, not a failure.
+ */
+export function projectDesignMap(previews, opts = {}) {
+  const variantRenders = variantRendersByComponent(previews);
+
+  const components = [];
+  const declarations = [];
+  /** Components carrying neither a reference nor a stated reason for its absence. */
+  const unmapped = [];
+  /**
+   * Components whose reference is absent for a STATED reason. Reported apart from `unmapped`
+   * because they are the opposite situation: someone looked, and what they found is that the kit
+   * has nothing live to point at. Rolling the two together is what made a retired pattern read as
+   * neglect.
+   */
+  const statedAbsent = [];
+
+  for (const preview of previews) {
+    const catalog = preview.catalog;
+    if (!catalog || catalog.role !== "COMPONENT") continue;
+    if (!LIGHT_CAPTURE.test(preview.id)) continue;
+
+    if (!catalog.reference) {
+      if (catalog.noReference) {
+        statedAbsent.push({ componentId: catalog.componentId, reason: catalog.noReference });
+      } else {
+        unmapped.push(catalog.componentId);
+      }
+      continue;
+    }
+
+    const code = codeHandle(preview, opts);
+    components.push({
+      code,
+      source: sourceForRef(catalog.reference),
+      ref: catalog.reference,
+      // The component SET, when the annotation names one. `ref` stays the one variant parity diffs
+      // against; `refSet` is what a whole-screen import matches an instance through, since a screen
+      // rarely uses the exact variant this sticker pictures. Absent unless the annotation says so.
+      ...(catalog.referenceSet ? { refSet: catalog.referenceSet } : {}),
+      // Figma normally exports only the referenced node. Preserve an explicit per-component opt-out
+      // when the annotation says this reference intentionally relies on overlapping sheet content.
+      ...(catalog.referenceContentsOnly === false ? { referenceContentsOnly: false } : {}),
+      previewId: preview.id,
+    });
+
+    const renders = variantRenders.get(catalog.componentId) ?? [];
+    if (renders.length) {
+      declarations.push({
+        code,
+        componentId: catalog.componentId,
+        reference: catalog.reference,
+        basePreviewId: preview.id,
+        renders,
+      });
+    }
+  }
+
+  components.sort((a, b) => a.code.localeCompare(b.code));
+  declarations.sort((a, b) => a.code.localeCompare(b.code));
+  unmapped.sort();
+  statedAbsent.sort((a, b) => a.componentId.localeCompare(b.componentId));
+
+  return {
+    map: { components },
+    variants: { schema: DESIGN_MAP_VARIANTS_SCHEMA, components: declarations },
+    diagnostics: {
+      unmapped,
+      statedAbsent,
+      variantRenders: declarations.reduce((n, d) => n + d.renders.length, 0),
+      withSet: components.filter((c) => c.refSet).length,
+    },
+  };
+}

package/emit-design-map.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * Write a repo's `design-map.json` from its discovery manifest — the I/O around `design-map.mjs`.
+ *
+ *     npx @yschimke/compose-design-map [--previews <path>] [--out design-map.json]
+ *                                      [--variants design-map-variants.json] [--prefix catalog]
+ *                                      [--check] [--strict]
+ *
+ * Run `./gradlew :<module>:composePreviewDiscover` first so the manifest exists.
+ *
+ * ## Two files out
+ *
+ * `--out` is the design map design-parity reads. `--variants` is the sidecar of **unresolved**
+ * variant declarations: which other previews are the same component with knobs turned, and which
+ * knobs. Turning those into design nodes needs a design kit's published vocabulary, which this repo
+ * does not hold — see the module KDoc in `design-map.mjs` for why the split falls here. A repo with
+ * no resolver still gets a valid map of base references from this alone.
+ *
+ * Both are **outputs**: regenerate rather than edit. `--check` is the CI posture — it regenerates
+ * in memory and exits non-zero if either committed file has drifted, without writing.
+ *
+ * ## Failure posture
+ *
+ * An unmapped component is reported, never fatal by default: a catalog is allowed to contain
+ * components nobody has mapped yet, and failing the build over one would make adding a component a
+ * breaking change.
+ *
+ * `--strict` is the opposite posture, for a catalog whose whole purpose is to reproduce a kit —
+ * there, a component with no kit node to compare against does not belong in the published
+ * inventory at all, and publishing it means shipping a sticker that can never be checked. It gates
+ * on BOTH kinds of absence: a missing `reference`, and one explained by `noReference`. The
+ * annotation still earns its keep in the default mode, where the two are reported apart so a
+ * retired pattern does not read as neglect; `--strict` simply says there are no exceptions.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { projectDesignMap } from "./design-map.mjs";
+
+function arg(name, def = undefined) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < process.argv.length && !process.argv[i + 1].startsWith("--")
+    ? process.argv[i + 1]
+    : def;
+}
+
+const PREVIEWS = arg("previews", "build/compose-previews/previews.json");
+const OUT = arg("out", "design-map.json");
+const VARIANTS_OUT = arg("variants", "design-map-variants.json");
+const PREFIX = arg("prefix", "catalog");
+const CHECK = process.argv.includes("--check");
+const STRICT = process.argv.includes("--strict");
+
+if (!fs.existsSync(PREVIEWS)) {
+  console.error(
+    `No discovery manifest at ${PREVIEWS}.\n` +
+      `Run \`./gradlew :<module>:composePreviewDiscover\` first, or pass --previews <path>.`,
+  );
+  process.exit(2);
+}
+
+const manifest = JSON.parse(fs.readFileSync(PREVIEWS, "utf8"));
+const { map, variants, diagnostics } = projectDesignMap(manifest.previews ?? [], {
+  prefix: PREFIX,
+});
+
+// Gate BEFORE writing, not after. A run that fails should leave the committed map intact rather
+// than replacing it with one CI would then report as merely stale — and an author who dropped a
+// whole group's references wants the list, not one name at a time.
+if (STRICT) {
+  const missing = [
+    ...diagnostics.unmapped.map((id) => `${id} — no reference, and no reason given`),
+    ...diagnostics.statedAbsent.map((s) => `${s.componentId} — ${s.reason}`),
+  ];
+  if (missing.length) {
+    console.error(
+      `::error::--strict: ${missing.length} component(s) carry no ` +
+        `@CatalogComponent(reference = …):`,
+    );
+    for (const line of missing) console.error(`  - ${line}`);
+    console.error(
+      `A catalog that reproduces a kit has nothing to compare these against — remove them, ` +
+        `or drop --strict to publish them unmapped.`,
+    );
+    process.exit(1);
+  }
+}
+
+const serialize = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const mapText = serialize(map);
+// A component with no variant renders needs no sidecar at all. Writing an empty one would put a
+// file in the repo whose only content is the assertion that it has nothing to say.
+const wantsVariants = variants.components.length > 0;
+const variantsText = serialize(variants);
+
+let drifted = false;
+function reconcile(file, text, wanted) {
+  const exists = fs.existsSync(file);
+  if (CHECK) {
+    const current = exists ? fs.readFileSync(file, "utf8") : null;
+    const expected = wanted ? text : null;
+    if (current !== expected) {
+      drifted = true;
+      const what = !wanted && exists ? "is stale and should be removed" : "is out of date";
+      console.error(`::error::${file} ${what} — regenerate with \`compose-design-map\`.`);
+    }
+    return;
+  }
+  if (!wanted) {
+    if (exists) {
+      fs.rmSync(file);
+      console.log(`Removed ${file} (no variant renders declare an axis).`);
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+reconcile(OUT, mapText, true);
+reconcile(VARIANTS_OUT, variantsText, wantsVariants);
+
+if (!CHECK) {
+  console.log(
+    `Wrote ${OUT}: ${map.components.length} mapped component(s), ` +
+      `${diagnostics.withSet} naming their component set.`,
+  );
+  if (wantsVariants) {
+    console.log(
+      `Wrote ${VARIANTS_OUT}: ${diagnostics.variantRenders} variant render(s) across ` +
+        `${variants.components.length} component(s), awaiting a kit resolver.`,
+    );
+  }
+}
+
+if (diagnostics.statedAbsent.length) {
+  console.log(
+    `\n${diagnostics.statedAbsent.length} component(s) have no reference for a stated reason — ` +
+      `the kit has nothing live to point at, which is a fact about the kit rather than a gap in ` +
+      `this catalog:`,
+  );
+  for (const s of diagnostics.statedAbsent) {
+    console.log(`  - ${s.componentId} — ${s.reason}`);
+  }
+}
+
+if (diagnostics.unmapped.length) {
+  console.log(
+    `\n${diagnostics.unmapped.length} component(s) carry neither ` +
+      `@CatalogComponent(reference = …) nor a noReference explaining why, and were skipped:`,
+  );
+  for (const id of diagnostics.unmapped) console.log(`  - ${id}`);
+}
+
+if (drifted) process.exit(1);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@yschimke/compose-design-map",
+  "version": "0.0.0",
+  "description": "Project a compose-preview discovery manifest into design-parity's design-map.json, plus a sidecar of unresolved variant declarations. Dependency-free.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./design-map.mjs",
+  "exports": {
+    ".": "./design-map.mjs"
+  },
+  "bin": {
+    "compose-design-map": "./emit-design-map.mjs"
+  },
+  "files": [
+    "design-map.mjs",
+    "emit-design-map.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "compose",
+    "compose-preview",
+    "design-parity",
+    "design-map",
+    "figma"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yschimke/compose-ai-tools.git",
+    "directory": "design-map"
+  },
+  "homepage": "https://github.com/yschimke/compose-ai-tools/tree/main/design-map#readme",
+  "bugs": "https://github.com/yschimke/compose-ai-tools/issues"
+}