@contentful/experience-design-system-generation 2.32.1-dev-build-1c12dc8.0 → 2.32.1-dev-build-b7d2d34.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.32.1-dev-build-1c12dc8.0",
+  "version": "2.32.1-dev-build-b7d2d34.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",

package/dist/src/prompt-builder.d.ts

@@ -68,6 +68,10 @@ export interface PromptOptions {
      * appropriate warning banner.
      */
     skillPathOverride?: string;
+    /** JSON-serialized summary of existing space Components. Callers pre-project the shape per skill. */
+    existingComponentsInline?: string;
+    /** JSON-serialized summary of existing space DesignTokens. Callers pre-project the shape per skill. */
+    existingTokensInline?: string;
 }
 export declare function buildPrompt(options: PromptOptions): Promise<string>;
 export declare function resolveSkillPath(skill: Skill): string;

package/dist/src/prompt-builder.js

@@ -129,8 +129,14 @@ function renderTokenCandidateSection(kind, entries) {
     return `${label}, one leaf token per line as \`path · type\`, no \`$value\`:\n${formatTokenCandidateLines(entries)}`;
 }
 function buildPreamble(options) {
-    const { skill, rawComponentsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, generatedCdf, tokenTree, componentSourceRefs, } = options;
+    const { skill, rawComponentsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, generatedCdf, tokenTree, componentSourceRefs, existingComponentsInline, existingTokensInline, } = options;
     const sections = [];
+    if (existingComponentsInline) {
+        sections.push(`Existing components in the target Contentful space (JSON) — use for alignment, not as a hard filter:\n\`\`\`json\n${existingComponentsInline}\n\`\`\``);
+    }
+    if (existingTokensInline) {
+        sections.push(`Existing design tokens in the target Contentful space (JSON) — prefer binding to these paths over inventing new ones:\n\`\`\`json\n${existingTokensInline}\n\`\`\``);
+    }
     if (rawComponentsInline) {
         sections.push(`Raw component data (JSON):\n\`\`\`json\n${rawComponentsInline}\n\`\`\``);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.32.1-dev-build-1c12dc8.0",
+  "version": "2.32.1-dev-build-b7d2d34.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     "skills/"
   ],
   "dependencies": {
-    "@contentful/experience-design-system-types": "2.32.1-dev-build-1c12dc8.0"
+    "@contentful/experience-design-system-types": "2.32.1-dev-build-b7d2d34.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",

package/skills/generate-components.md

@@ -549,3 +549,30 @@ If you are genuinely uncertain about every prop, classify each as:
 An imperfect classification is infinitely better than no classification. That is
 about **classifying a prop rather than dropping it** — it is not a licence to
 invent a `values` list. The uncertain answer is `cdf_type: "string"`, every time.
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing components in the target Contentful space" JSON block with a `likelyMatch` (a fuzzy-matched space component that likely corresponds to the codebase component you're classifying), an `otherComponents` list, and a rolled-up token summary. Use it to align your classifications with what the customer already has.
+
+### When `likelyMatch` is present — align prop names, categories, and slot names
+
+Your goal is **consistency**: the customer will see the diff between what you propose and what already exists, and every unnecessary rename or category flip becomes review friction.
+
+1. **Prop names**: if the codebase has a prop whose meaning matches a `likelyMatch` design/content property (e.g. codebase `kind` ↔ space `variant`, codebase `text` ↔ space `label`), emit `classify_prop` with the **space's prop name** rather than the codebase name. In the `reason` field, always explain the rename explicitly, e.g. `"renamed from codebase prop 'kind' to match existing space prop 'variant'"`. If you can't confidently identify the correspondence, keep the codebase name.
+2. **Categories**: match the space's category (`design` / `content`) for equivalent props, even if you'd normally categorize differently. Note the alignment in `reason`.
+3. **Slot names**: match slot IDs / names when the shape is equivalent.
+4. **Enum values**: never invent new values to bridge a mismatch. If the codebase's enum diverges from the space's, classify against your best-effort mapping and cite the divergence in `reason` — this is a signal for human review, not a green light to rewrite the space's enum.
+5. **Never rename or realign silently.** Every classification influenced by the `likelyMatch` MUST cite it in `reason`.
+
+### When only `otherComponents` is present (no direct match)
+
+Use the list to constrain slot `allowedComponents` — do not propose a slot that accepts component types the space doesn't have.
+
+### Token binding
+
+The preamble's "Existing design tokens" section lists tokens (by name + DTCG type) already in the space.
+
+1. When classifying a `design`-category, `token`-typed prop, prefer binding to an existing token name over inventing a new one. Cite the target token in `reason`.
+2. If no existing token semantically matches, proceed with the current rules — propose a new token. The diff surfaces this for review.

package/skills/map-tokens.md

@@ -88,3 +88,15 @@ Before emitting any tool calls, verify:
 3. `token_allowed` is never empty.
 4. Every emitted list includes the prop's own default token when it has one.
 5. No list was emitted on the strength of a default alone, and none targets a prop whose type is a union of variant names.
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing design tokens in the target Contentful space" JSON block listing tokens already present in the target space (by name + DTCG type).
+
+Prefer restricting to existing tokens over proposing new ones:
+
+1. When the source has restriction evidence AND a candidate maps semantically to an existing token by name/type, favor the existing token in the emitted `token_allowed` list.
+2. Never emit a `token_allowed` entry that contradicts the "path exists verbatim" rule above — the existing-tokens block is guidance, not a substitute for the token path index. If a token appears in the existing-entities list but not in the token path index, do not use it.
+3. If none of the existing tokens fit and the source's evidence is specific, proceed as usual — the diff will surface the new proposal.

package/skills/select-components.md

@@ -222,3 +222,14 @@ TextImageCard — card with rich text and background image
 SearchInput — search field with dropdown
 {"tool":"select_component","name":"SearchInput","reason":"search UI — configurable placeholder and state"}
 ```
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing components in the target Contentful space" JSON block and a rolled-up token summary. Use them as **signal, not as a filter**. Rules:
+
+1. Never let a name overlap force a decision. Acceptance is still driven purely by "does the codebase component render visible, authorable UI?" — a name match does not auto-accept, and a name conflict does not auto-reject.
+2. When a codebase component appears to correspond to an existing space component (name overlap, semantic overlap in the description), note it in your `reason` — e.g. `"accepted; likely maps to existing space component 'Button'"`. This surfaces the mapping for downstream review.
+3. When the space is mature (many existing components, dozens of tokens) and the codebase has thin wrappers with no visible UI difference, lean harder toward rejecting the wrappers. Extra noise in a mature space is more costly than in an empty one.
+4. When no overlap exists, the acceptance decision is unchanged from the rules above.