@contentful/experience-design-system-generation 2.27.5-dev-build-6ae590e.0 → 2.27.5-dev-build-67ce1cd.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.27.5-dev-build-6ae590e.0",
+  "version": "2.27.5-dev-build-67ce1cd.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",
@@ -33,7 +33,7 @@
     "@contentful/experience-design-system-types": "workspace:*"
   },
   "devDependencies": {
-    "@tsconfig/node24": "^24.0.5",
+    "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.0.3",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",

package/dist/src/agent-runner.d.ts

@@ -89,6 +89,18 @@ export interface ParsedToolCalls {
 }
 export declare function parseToolCallLines(stdout: string): ParsedToolCalls;
 export declare function parseTokenToolCallLines(stdout: string): ParsedTokenToolCalls;
+export interface MapTokenPropCall {
+    tool: 'map_token_prop';
+    component: string;
+    prop: string;
+    /** Narrowed subset of tokens the prop may draw from. Required and non-empty. */
+    token_allowed: string[];
+}
+export interface ParsedMapTokenPropToolCalls {
+    calls: MapTokenPropCall[];
+    warnings: string[];
+}
+export declare function parseMapTokenPropToolCallLines(stdout: string): ParsedMapTokenPropToolCalls;
 export declare function resolveBinary(agent: AgentName): string;
 /**
  * Resolve the model for an agent. Explicit flag/creds value wins, then a

package/dist/src/agent-runner.js

@@ -220,6 +220,51 @@ export function parseTokenToolCallLines(stdout) {
     }
     return { calls, warnings };
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+export function parseMapTokenPropToolCallLines(stdout) {
+    const calls = [];
+    const warnings = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('{'))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            warnings.push(`unparseable line: ${line.slice(0, 120)}`);
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null || !('tool' in obj))
+            continue;
+        const rec = obj;
+        if (rec.tool !== 'map_token_prop')
+            continue; // not a map-tokens call — skip silently
+        if (typeof rec.component !== 'string' || !rec.component) {
+            warnings.push('map_token_prop missing component — skipped');
+            continue;
+        }
+        if (typeof rec.prop !== 'string' || !rec.prop) {
+            warnings.push(`map_token_prop '${rec.component}': missing prop — skipped`);
+            continue;
+        }
+        if (!isStringArray(rec.token_allowed) || rec.token_allowed.length === 0) {
+            warnings.push(`map_token_prop '${rec.component}.${String(rec.prop)}': missing or empty token_allowed — skipped`);
+            continue;
+        }
+        const call = {
+            tool: 'map_token_prop',
+            component: rec.component,
+            prop: rec.prop,
+            token_allowed: rec.token_allowed,
+        };
+        calls.push(call);
+    }
+    return { calls, warnings };
+}
 // --- Agent invocation ---
 const AGENT_BINARIES = {
     claude: 'claude',

package/dist/src/index.d.ts

@@ -1,9 +1,9 @@
 export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName } from './agent-names.js';
 export type { AgentName } from './agent-names.js';
-export { buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, resolveAgentModel, resolveBinary, runAgent, } from './agent-runner.js';
-export type { AgentAuthStatus, AgentDebugEvent, AgentRunResult, ClassifyComponentCall, ClassifyPropCall, ClassifySlotCall, ExcludePropCall, ParsedSelectToolCalls, ParsedTokenToolCalls, ParsedToolCalls, RejectComponentCall, SelectComponentCall, SelectToolCall, SetGroupCall, SetTokenCall, ToolCall, TokenToolCall, } from './agent-runner.js';
+export { buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseMapTokenPropToolCallLines, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, resolveAgentModel, resolveBinary, runAgent, } from './agent-runner.js';
+export type { AgentAuthStatus, AgentDebugEvent, AgentRunResult, ClassifyComponentCall, ClassifyPropCall, ClassifySlotCall, ExcludePropCall, MapTokenPropCall, ParsedMapTokenPropToolCalls, ParsedSelectToolCalls, ParsedTokenToolCalls, ParsedToolCalls, RejectComponentCall, SelectComponentCall, SelectToolCall, SetGroupCall, SetTokenCall, ToolCall, TokenToolCall, } from './agent-runner.js';
 export { createLocalCliAgentInvoker } from './agent-invoker.js';
 export type { AgentInvoker, CreateLocalCliAgentInvokerOptions, InvokeAgentOptions } from './agent-invoker.js';
 export { buildPrompt, formatCustomPromptBanner, resolveSkillPath } from './prompt-builder.js';
-export type { Mode, PromptOptions, Skill } from './prompt-builder.js';
+export type { ComponentSourceRef, GeneratedCdf, Mode, PromptOptions, Skill } from './prompt-builder.js';
 export { formatGenerateProgressLine } from './progress.js';

package/dist/src/index.js

@@ -1,7 +1,7 @@
 // Agent identity
 export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName } from './agent-names.js';
 // Agent invocation (low-level)
-export { buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, resolveAgentModel, resolveBinary, runAgent, } from './agent-runner.js';
+export { buildArgs, checkAgentAuth, describeAgentFailure, extractSentinelOutput, parseMapTokenPropToolCallLines, parseSelectToolCallLines, parseTokenToolCallLines, parseToolCallLines, resolveAgentModel, resolveBinary, runAgent, } from './agent-runner.js';
 // Agent invocation (interface)
 export { createLocalCliAgentInvoker } from './agent-invoker.js';
 // Prompt building

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

@@ -1,6 +1,41 @@
-/** `components` — classify component props; `tokens` — classify design tokens; `select` — decide whether a component belongs in Contentful Experience Orchestration */
-export type Skill = 'components' | 'tokens' | 'select';
+import { type CDFComponentEntry } from '@contentful/experience-design-system-types';
+/** `components` — classify component props; `tokens` — classify design tokens; `select` — decide whether a component belongs in Contentful Experience Orchestration; `map-tokens` — suggest `$token.allowed` restrictions for design-category token props */
+export type Skill = 'components' | 'tokens' | 'select' | 'map-tokens';
 export type Mode = 'autonomous';
+/**
+ * A component name paired with the source file it was extracted from, for
+ * token-mapping evidence. `content` is the real file text (bounded, see
+ * MAX_COMPONENT_SOURCE_CHARS) — this pipeline is agent-fs-free by design (see
+ * generate-components.md's "you do not write any files"), so the caller must
+ * read the file itself and inline the text here rather than handing the
+ * agent a path and expecting it to open the file. `null` when the file
+ * couldn't be read (moved/deleted since extraction) — callers fall back to
+ * inferring from the prop name and $token.kind alone in that case.
+ * `siblingFiles` carries the content of files the source file relatively
+ * imports (e.g. a co-located `.styles.ts`) — token-resolution logic often
+ * lives one hop away from the component file itself. `truncatedSiblingCount`
+ * is set when the caller found more resolvable sibling files than it inlines
+ * (see MAX_SIBLING_FILES) — surfaced in the prompt so the classifier knows
+ * evidence was dropped rather than that the search came up empty.
+ */
+export interface ComponentSourceRef {
+    component: string;
+    sourcePath: string;
+    content: string | null;
+    siblingFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    truncatedSiblingCount?: number;
+    /**
+     * Properties with at least one use that fell outside the excerpt budget of
+     * the file it sits in. The reader cannot see that use, so its absence is a
+     * gap in the evidence, not evidence of absence.
+     */
+    usesNotShown?: string[];
+}
+/** Plain-data shape of the CDF generated so far — component name -> component entry. */
+export type GeneratedCdf = Record<string, CDFComponentEntry>;
 /**
  * Render the warning banner shown when a custom skill prompt is active.
  * Always cites the bundled invariants that the override bypasses so the
@@ -19,6 +54,12 @@ export interface PromptOptions {
     outDir: string;
     /** For components skill only: the single component's name (used in error messages). */
     componentName?: string;
+    /** For map-tokens skill: the CDF generated so far. Filtered internally to design-category token-typed props only. */
+    generatedCdf?: GeneratedCdf;
+    /** For map-tokens skill: the full DTCG token tree. Flattened internally to a path+`$type` index, with `$value` stripped. */
+    tokenTree?: Record<string, unknown>;
+    /** Component source file references — consumption evidence for the components skill, explicit-restriction evidence (comments, allowlists) for map-tokens. */
+    componentSourceRefs?: ComponentSourceRef[];
     /**
      * Feature 8: custom prompt path override. When set, this absolute or relative
      * `.md` path is read in place of the bundled skill file. The bundled-prompt

package/dist/src/prompt-builder.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { flattenDTCG } from '@contentful/experience-design-system-types';
 /**
  * Render the warning banner shown when a custom skill prompt is active.
  * Always cites the bundled invariants that the override bypasses so the
@@ -16,6 +17,7 @@ const SKILL_FILES = {
     components: 'generate-components.md',
     tokens: 'generate-tokens.md',
     select: 'select-components.md',
+    'map-tokens': 'map-tokens.md',
 };
 export async function buildPrompt(options) {
     const skillContent = await readSkillFile(options.skill, options.skillPathOverride);
@@ -68,6 +70,11 @@ function inferFenceLang(filename) {
         ts: 'ts',
         mts: 'ts',
         cts: 'ts',
+        tsx: 'tsx',
+        jsx: 'jsx',
+        vue: 'vue',
+        svelte: 'svelte',
+        astro: 'astro',
         scss: 'scss',
         sass: 'scss',
         css: 'css',
@@ -76,8 +83,53 @@ function inferFenceLang(filename) {
     };
     return map[ext] ?? 'text';
 }
+/**
+ * Keeps only design-category, token-typed props per component (dropping
+ * components left with none), alongside the distinct `$token.kind` values
+ * seen among them and whether any such prop has no `$token.kind` at all —
+ * collected in the same pass rather than a second walk of the raw CDF.
+ */
+function filterDesignTokenProps(cdf) {
+    const result = {};
+    const kinds = new Set();
+    let hasUnscoped = false;
+    for (const [componentName, component] of Object.entries(cdf)) {
+        const properties = component.$properties;
+        if (!properties)
+            continue;
+        const filteredProps = {};
+        for (const [propName, prop] of Object.entries(properties)) {
+            if (prop.$type === 'token' && prop.$category === 'design') {
+                const { '$token.allowed': _tokenAllowed, ...rest } = prop;
+                filteredProps[propName] = rest;
+                const kind = prop['$token.kind'];
+                if (typeof kind === 'string' && kind.length > 0) {
+                    kinds.add(kind);
+                }
+                else {
+                    hasUnscoped = true;
+                }
+            }
+        }
+        if (Object.keys(filteredProps).length > 0) {
+            result[componentName] = { ...component, $properties: filteredProps };
+        }
+    }
+    return { filtered: result, kinds: [...kinds].sort(), hasUnscoped };
+}
+/** One line per candidate, e.g. `colors.brand.primary · color` — legible and countable, unlike nested JSON. */
+function formatTokenCandidateLines(entries) {
+    return entries.map((entry) => `${entry.path} · ${entry.$type}`).join('\n');
+}
+/** Renders one kind-scoped (or, for `kind: null`, full-tree) candidate section. Sections are cumulative, never merged, so each stays independently legible. */
+function renderTokenCandidateSection(kind, entries) {
+    const label = kind
+        ? `Token path index — ${kind} candidates only`
+        : 'Token path index — full tree (no $token.kind to scope by)';
+    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 } = options;
+    const { skill, rawComponentsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, generatedCdf, tokenTree, componentSourceRefs, } = options;
     const sections = [];
     if (rawComponentsInline) {
         sections.push(`Raw component data (JSON):\n\`\`\`json\n${rawComponentsInline}\n\`\`\``);
@@ -93,6 +145,56 @@ function buildPreamble(options) {
     if (tokenMapInline) {
         sections.push(`Token-name sidecar (raw name → DTCG path):\n\`\`\`json\n${tokenMapInline}\n\`\`\``);
     }
+    const filteredTokenProps = generatedCdf ? filterDesignTokenProps(generatedCdf) : undefined;
+    if (filteredTokenProps && Object.keys(filteredTokenProps.filtered).length > 0) {
+        sections.push(`Generated CDF so far — design-category token props only (JSON):\n\`\`\`json\n${JSON.stringify(filteredTokenProps.filtered)}\n\`\`\``);
+    }
+    if (tokenTree) {
+        const index = flattenDTCG(tokenTree, '').sort((a, b) => a.path.localeCompare(b.path));
+        if (index.length > 0) {
+            if (filteredTokenProps) {
+                const { kinds, hasUnscoped } = filteredTokenProps;
+                for (const kind of kinds) {
+                    const scoped = index.filter((entry) => entry.$type === kind);
+                    if (scoped.length > 0)
+                        sections.push(renderTokenCandidateSection(kind, scoped));
+                }
+                if (hasUnscoped)
+                    sections.push(renderTokenCandidateSection(null, index));
+            }
+            else {
+                sections.push(renderTokenCandidateSection(null, index));
+            }
+        }
+    }
+    if (componentSourceRefs && componentSourceRefs.length > 0) {
+        const withContent = componentSourceRefs.filter((ref) => ref.content != null);
+        const withoutContent = componentSourceRefs.filter((ref) => ref.content == null);
+        if (withContent.length > 0) {
+            const blocks = withContent.map((ref) => {
+                const mainBlock = `#### ${ref.component} (\`${ref.sourcePath}\`)\n\`\`\`${inferFenceLang(ref.sourcePath)}\n${ref.content}\n\`\`\``;
+                const siblingBlocks = (ref.siblingFiles ?? []).map((sibling) => `##### ${ref.component} — imported file \`${sibling.path}\`\n\`\`\`${inferFenceLang(sibling.path)}\n${sibling.content}\n\`\`\``);
+                const truncationNote = ref.truncatedSiblingCount && ref.truncatedSiblingCount > 0
+                    ? [
+                        `##### ${ref.component} — +${ref.truncatedSiblingCount} more imported file${ref.truncatedSiblingCount === 1 ? '' : 's'} not shown (evidence may be incomplete)`,
+                    ]
+                    : [];
+                const notShownNote = ref.usesNotShown && ref.usesNotShown.length > 0
+                    ? [
+                        `##### ${ref.component} — uses not shown: ${ref.usesNotShown.join(', ')}\n\nThe files above are excerpts, and each of these properties has at least one use that fell outside the excerpt budget. Treat their consumption as unknown, not absent: do not classify them \`token\` on what is shown, and do not conclude they are unread.`,
+                    ]
+                    : [];
+                return [mainBlock, ...siblingBlocks, ...truncationNote, ...notShownNote].join('\n\n');
+            });
+            sections.push(`### Component source references\n\n${blocks.join('\n\n')}`);
+        }
+        if (withoutContent.length > 0) {
+            const guidance = skill === 'components'
+                ? 'there is no consumption evidence for these, so `token` cannot be earned for any of their props — classify from the prop signature alone, and any prop that would otherwise be enum-versus-token is `enum` (or `string`)'
+                : 'there is no source evidence to narrow from — emit nothing for their props';
+            sections.push(`Component source unavailable for (JSON) — ${guidance}:\n\`\`\`json\n${JSON.stringify(withoutContent.map((ref) => ({ component: ref.component, sourcePath: ref.sourcePath })))}\n\`\`\``);
+        }
+    }
     const inputBlock = sections.length > 0 ? `\n\n${sections.join('\n\n')}` : '';
     if (skill === 'components') {
         return buildComponentsAutonomousPreamble(inputBlock);
@@ -100,6 +202,9 @@ function buildPreamble(options) {
     if (skill === 'select') {
         return buildSelectAutonomousPreamble(inputBlock);
     }
+    if (skill === 'map-tokens') {
+        return buildMapTokensAutonomousPreamble(inputBlock);
+    }
     return buildTokensAutonomousPreamble(inputBlock);
 }
 function buildComponentsAutonomousPreamble(inputBlock) {
@@ -110,8 +215,6 @@ Context: You are classifying a React component for **Contentful Experience Orche
 - **content**: the data a content editor fills in (text, images, URLs, rich text)
 - **state**: runtime behavioral flags (disabled, loading, expanded, identifiers)
 
-For props with complex TypeScript types (named types, enums): reason from the prop name and type name to classify them. Do not automatically exclude a prop just because its type is a named reference — infer the likely values and classify it as enum if it controls appearance.
-
 Your task: classify every prop and slot in the component below. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a "description" field on each tool call to document your reasoning so the developer can review it afterward.
 
 All input data is provided inline below — do not read any additional files.${inputBlock}
@@ -138,10 +241,12 @@ Rules:
 - Every slot in the input must have exactly one classify_slot call.
 - Valid cdf_type values: string, richtext, media, enum, token, boolean
 - Valid cdf_category values: content, design, state
-- For enum type, always include "values" (non-empty string array).
-- For token type, always include "token_kind" (DTCG \$type, e.g. "color").
-- href and URL props → cdf_type "string", cdf_category "content". Do NOT use cdf_type "link" — it is not valid.
-- Framework internals (ref, event handlers, test IDs) → exclude_prop.
+- For enum type, always include \`values\` (non-empty string array of the variant names the prop accepts).
+- For token type, always include \`token_kind\` (DTCG \$type, e.g. "color"). **Never emit \`values\` for \`cdf_type: "token"\` props** — an enum prop's list holds variant names; a token prop's list holds design token paths, produced separately and never by you. Emitting \`values\` on a token prop makes the definition invalid.
+- Never emit both "values" and "token_kind" on one prop.
+- \`enum\` vs \`token\` is decided by three questions answered in order from the source shown — never from the TypeScript type. Q1: does the component look the value up, switch on it, or have a vocabulary for it (\`tokens[x]\`, \`switch (variant)\`, \`allowedValues\`)? yes → \`enum\`, stop.
+- Q2: is the value written straight into a style or attribute (\`rx={radius}\`, \`padding: \${padding}\`)? no → not \`token\`, apply the type rules.
+- Q3: is there a design-token reference at that use — a \`tokens.*\` parameter default, a \`tokenReference\`, an inline \`tokens.*\` / \`var(--*)\`? yes → \`token\` (cite both lines in "reason"); no → \`string\`. "Ambiguity resolves to \`enum\`" applies only when Q1–Q3 cannot be answered from the source shown.
 - CSS design props (className, style, styles, positional/geometric props: top, bottom, left, right, rotation, offset, etc.) → classify_prop, cdf_type: "string", cdf_category: "design".
 - On classify_component, "rationale" fields are operator-facing (read-only) but may surface in customer-facing exports. The "rationale.description" field is subject to the description content rules in the skill prompt (no internal initiative names). "rationale.props" and "rationale.slots" describe your reasoning about scope; "classify_slot.rationale" explains why each slot was kept.
 - On classify_prop, "reason" is REQUIRED and is the LLM's internal rationale — shown to the developer reviewing the import, never to end-users. "description" is the customer-facing copy and is subject to the description content rules in the skill prompt. Keep them distinct: "description" is short and customer-facing; "reason" explains your reasoning in detail.
@@ -173,6 +278,31 @@ Rules:
 - Emit exactly one tool call per input component. The "name" field must match a component name from the input array exactly. Tool calls may appear in any order.
 - You may emit prose lines (not starting with {) to reason before each tool call — they are ignored by the parser.`;
 }
+function buildMapTokensAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Context: The components below already have design-category, token-typed props (\`$token.kind\` set). Your task is to decide, from source evidence, whether to narrow each one to a restricted subset (\`token_allowed\`) of the tokens matching its \`$token.kind\`. Apply all judgment calls yourself — do not pause to ask for confirmation.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per line to stdout for each prop you narrow. The CLI reads your stdout line by line and writes each decision directly to the pipeline database.
+
+The one tool call you may emit:
+
+\`\`\`
+{"tool":"map_token_prop","component":"<ComponentName>","prop":"<propName>","token_allowed":["colors.brand.primary","colors.brand.secondary"]}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences around the lines.
+- Only emit a call for a prop that appears in the "Generated CDF so far" section.
+- Each "Token path index" section below is already scoped to one \`$token.kind\` — a prop only draws candidates from the section matching its own \`$token.kind\` (or the "full tree" section, for a prop with no \`$token.kind\`). Never cross sections, never emit a group/prefix path, and never invent a path — every entry in \`token_allowed\` must exist verbatim in the matching section.
+- \`token_allowed\` is required and must be non-empty when the call is emitted.
+- For the judgment call of whether a prop should be narrowed at all, follow the decision tree in the map-tokens skill file: it explains defaults vs. restrictions, misclassified variant-name props, and when to emit nothing.
+- You may emit prose lines (not starting with \`{\`) anywhere — they are ignored by the parser and serve as your reasoning log.`;
+}
 function buildTokensAutonomousPreamble(inputBlock) {
     return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.27.5-dev-build-6ae590e.0",
+  "version": "2.27.5-dev-build-67ce1cd.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",
@@ -22,10 +22,10 @@
     "skills/"
   ],
   "dependencies": {
-    "@contentful/experience-design-system-types": "2.27.5-dev-build-6ae590e.0"
+    "@contentful/experience-design-system-types": "2.27.5-dev-build-67ce1cd.0"
   },
   "devDependencies": {
-    "@tsconfig/node24": "^24.0.5",
+    "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.0.3",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",

package/skills/generate-components.md

@@ -29,6 +29,8 @@ All input is embedded inline in the prompt before this file:
 - **Raw component data** — `RawComponentDefinition[]` (one component for this run)
 - **DTCG token data** — full token tree, if provided
 - **Token-name sidecar** — raw CSS custom property name → DTCG dot-notation path, if provided
+- **Component source references** — the real file text for the component's own source, plus up to 5 sibling files (e.g. a co-located `.styles.ts` or `utils.ts`, or a file reached transitively through another sibling — such as a re-exported component's own styles module), if provided. **You have no filesystem access and no tools — `sourcePath` is a citation label only, never something to open.**
+  - A **"uses not shown"** line may accompany these files. The files are excerpts windowed around the property names, and this line names the properties with at least one use that fell outside the excerpt budget. Treat those properties' consumption as unknown: do not classify them `token` on what is shown, and do not conclude they are unread. Unknown resolves to `enum` (or `string`) per "Ambiguity resolves to `enum`".
 
 ```typescript
 interface RawPropDefinition {
@@ -39,7 +41,7 @@ interface RawPropDefinition {
   allowedValues?: string[];
   defaultValue?: string;
   description?: string;
-  tokenReference?: string;  // raw token name, e.g. "--brand-primary"
+  tokenReference?: string;  // raw token name — shape varies by design system, e.g. "--brand-primary" (CSS custom property) or "tokens.blue500" (flat/dotted JS reference)
 }
 
 interface RawSlotDefinition {
@@ -89,7 +91,8 @@ Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not
 - Every prop in the input must produce exactly one call: `classify_prop` OR `exclude_prop`.
 - Every slot must produce exactly one `classify_slot` call.
 - Emit `classify_component` once at the start (required). The `description` field is **required** — always provide a brief description of the component's purpose.
-- `values` is required for `cdf_type: "enum"` — must be a non-empty string array.
+- `values` is required for `cdf_type: "enum"` — must be a non-empty string array of the variant names the prop accepts.
+- **Do NOT include `values` for `cdf_type: "token"`.** The two property types carry different kinds of list. An `enum` prop's list holds *variant names* the component accepts (`"primary"`, `"secondary"`). A `token` prop's list holds *design token paths* (`"color.brand.primary"`), produced by the separate token-mapping step (`$token.allowed`) — never by you. Emitting `values` on a token prop makes the definition invalid.
 - `token_kind` is required for `cdf_type: "token"` — must be a DTCG `$type` string, e.g. `"color"`.
 - `required` must be a JSON boolean (`true`/`false`), not a string.
 - `description` on `classify_prop` is customer-facing — keep it short and subject to the description content rules below.
@@ -129,6 +132,99 @@ Exactly **6** valid types:
 
 ---
 
+### `enum` versus `token`
+
+Both describe a closed set of choices, but the *contents* differ, and that is the whole distinction:
+
+| | What the list holds | Example |
+|---|---|---|
+| `enum` | Variant names the component accepts | `["primary", "secondary", "ghost"]` |
+| `token` | Design token paths the prop may bind to | `["color.brand.primary", "color.brand.neutral"]` |
+
+The distinction is **what the component does with the value it receives**. That
+is decidable from source; it is not inferred from the property's name, from the
+component's role, or from the property's TypeScript type.
+
+An `enum` design property is delivered as a plain string, so the component
+receives `variant="primary"` — the value its own code branches on. A `token`
+property is resolved to the token's value *before* it reaches the component, so
+that same component would receive `variant="#0059c8"` and match no branch.
+
+#### The three-question procedure (closed, ordered)
+
+For every design prop that carries a value (not a boolean), answer these three
+questions **in this order**, from the source shown, and stop at the first answer
+that decides. There is no fourth question.
+
+- **Q1 — Does the component look the value up, switch on it, or compare it against names?**
+  An indexed access (`tokens[fontColor]`, `SPACING[padding]`, a `Record<Variant, Token>`),
+  a `switch (variant)` / `if (variant === 'x')` chain, a `styles[variant]` class lookup,
+  or a vocabulary of its own (`allowedValues`, a literal union) — any of these means
+  the component needs the *name*. A presence check (`if (width)`) or arithmetic on
+  the value is not a lookup.
+  **Yes → `enum`, names in `values`, stop.** No → Q2.
+- **Q2 — Is the value written straight into a style or attribute?**
+  `rx={radius}`, `padding: ${padding}`, `style={{ color }}`, `background: var(${bg})` —
+  the value reaches the renderer without the component resolving it.
+  **No → not `token`; leave this procedure and continue with the type rules.** Yes → Q3.
+- **Q3 — Is there a design-token reference at that use?** Any one of:
+  the parameter default is a token (`radius = tokens.borderRadiusSmall`), the raw prop
+  carries a `tokenReference`, or an inline `tokens.*` / `var(--*)` sits in the same
+  expression. The reference must belong to *this* prop — a `tokens.*` on some other
+  line of the file, or in a sibling's style object, is not one.
+  **Yes → `token`, stop; resolve `token_kind` from that reference. No → `string`, stop.**
+
+**The raw TypeScript type is not an input to Q1–Q3.** `string`, `number`,
+`string | number`, `stringOrNumber` — none of these answers any question above;
+they say what the compiler accepts, not what the component does with the value.
+"The type accepts any value, the default just happens to be a token reference" is
+a Q3-yes described as a no: a token parameter default *is* the design-token
+reference Q3 asks for, and the prop is `token`. Equally, a prop named `color` with
+no lookup and no token reference is `string`, however token-like the name.
+
+**Two worked examples — same shape, opposite answers:**
+
+```tsx
+// Divider.tsx
+export const Divider = ({ thickness = tokens.borderWidthDefault, inset = 0 }: DividerProps) => (
+  <hr style={{ borderTopWidth: thickness, marginLeft: inset }} />
+);
+```
+
+- `thickness` — Q1: no lookup. Q2: yes, `borderTopWidth: thickness`. Q3: yes, the
+  parameter default is `tokens.borderWidthDefault`. → **`token`**, `token_kind` from
+  `borderWidthDefault` via the sidecar. Its `string | number` annotation changes nothing.
+- `inset` — Q1: no lookup. Q2: yes, `marginLeft: inset`. Q3: no, the default is the
+  bare number `0` and nothing at this use is a token. → **`string`**, `default: "0"`.
+
+A lookup map from variant names to tokens is evidence **for** `enum`, not against
+it — that is Q1 answering yes. The map exists precisely because the component was
+handed a name it had to resolve itself.
+
+**`token` is earned by Q2 and Q3 together, and only that way.** Cite both lines
+in `reason`: the interpolation and the token reference. Once both are cited, the
+prop is `token` — do not then downgrade it because of its type annotation, because
+the default "could be overridden" (every default can), or because the tie-break
+below exists. Nothing downstream re-derives, corrects, or second-guesses this —
+what you emit is what ships.
+
+**Ambiguity resolves to `enum` — but only when Q1–Q3 cannot be answered.** The
+tie-break applies solely when the source shown does not let you answer the three
+questions: the property is interpolated in one place and looked up in another,
+the use sits in a file you cannot see, or the source is truncated at the point
+of use (the "uses not shown" line). In those cases emit `enum` (or `string` when
+it has no value set) and record the ambiguity in `reason`. When the three
+questions *can* be answered from the source shown, they are answered and the
+tie-break does not apply: a clear Q1-yes is `enum`, a clear Q2-yes + Q3-yes is
+`token`, and a type annotation does not create ambiguity. An `enum` is delivered
+as the plain string the component was written to receive and remains reachable
+from a content-type field; a wrong `token` delivers a resolved value the
+component cannot branch on and is permanently excluded from content-type field
+mapping. That asymmetric cost is why a genuine tie goes to `enum` — it is not a
+reason to call a decided case a tie.
+
+---
+
 ## Valid cdf_category values
 
 | cdf_category | Use case |
@@ -145,14 +241,18 @@ The pre-classified `category` in the raw input is a starting point — correct i
 
 For each `RawPropDefinition`, apply in order:
 
-1. **Framework / DOM / accessibility pass-through?** → `exclude_prop`. These are escape hatches for developers, not configurable surfaces for marketers. Exposing them in the ExO editor adds noise that obscures the props that actually carry intent. Always exclude:
+1. **Framework / DOM / accessibility pass-through?** → `exclude_prop`. These are escape hatches for developers, not configurable surfaces for marketers. Exposing them in the ExO editor adds noise that obscures the props that actually carry intent.
+
+   **The governing principle:** a prop is pass-through if it is inherited from a base interface the component extends (`React.HTMLAttributes<...>`, `AllHTMLAttributes`, a native element's attribute interface, an ARIA-attributes interface, etc.) or is one of a small set of universal framework hooks, **and the component does not redeclare or give it component-specific meaning**. Test this from the type declaration, not from name-matching against a list — a component that `extends React.HTMLAttributes<HTMLDivElement>` inherits `title`, `lang`, `translate`, `slot`, and dozens more that a fixed list will never enumerate; a component that redeclares one of these with its own type or JSDoc (e.g. its own `title: string` documented as "card heading") has given it new meaning and it is no longer pass-through.
+
+   Always exclude under this principle:
    - Framework internals: `ref`, `innerRef`, event handlers (any `onSomething`), `testId`, `data-testid`, `key`
-   - DOM pass-through: `className`, `class`, `classes`, `classNames`, `rootClassName`, `prefixCls`, `style`, `styles`, `id`, `role`, `tabIndex`, `htmlFor`, `for`, `slot`, `is`, `lang`, `dir`, `hidden`, `draggable`, `spellCheck`, `contentEditable`, `inputMode`, `autoComplete`, `autoFocus`, `translate`, `part`, `exportparts`
+   - Any prop inherited from an HTML-attributes base interface and not redeclared by the component — this replaces any fixed name list. Common examples include `className`, `class`, `classes`, `classNames`, `rootClassName`, `prefixCls`, `style`, `styles`, `id`, `role`, `tabIndex`, `htmlFor`, `for`, `slot`, `is`, `lang`, `dir`, `hidden`, `draggable`, `spellCheck`, `contentEditable`, `inputMode`, `autoComplete`, `autoFocus`, `translate`, `part`, `exportparts` — but these are examples of the principle, not an exhaustive list; apply the inheritance test to any prop the examples don't cover.
    - Accessibility pass-through: any `aria-*` or `ariaSomething` prop (including bare `aria` as an aria-attributes object), `aria-label`, `aria-hidden`, `aria-describedby`, `aria-controls`
    - Data attributes: any `data-*` prop
    - **Polymorphic component props**: `as`, `element`, `component` (when typed as an HTML tag string or component reference) — these change rendered HTML, not marketer-visible behavior
    - **Framework theming / pass-through escape hatches**: PrimeVue's `dt` / `pt` / `ptOptions` / `unstyled`, MUI/Chakra-style `sx`, anything explicitly typed as a developer "override" / "passthrough" object
-   - **Important caveat**: only exclude when the prop is one of these *as the bare HTML attribute or framework-internal pass-through*. Compound names like `fileName`, `displayName`, `dataset`, `dataSource`, `roleDescription`, `idLabel` are not pass-through — classify them normally.
+   - **Important caveat**: only exclude when the prop is inherited/universal *and unredeclared*. Compound names like `fileName`, `displayName`, `dataset`, `dataSource`, `roleDescription`, `idLabel` are not pass-through — classify them normally. Likewise, a `title` (or any other inherited-attribute name) that the component redeclares with its own type or doc comment is component-specific content, not pass-through — classify it per rule 2 onward, do not exclude it and do not route it through the `title` → `content` correction below.
 2. **Common semantic props — DO classify, do not exclude.** The LLM has been over-excluding these because they sound like framework internals; they are not. Classify each per the rest of this tree:
    - `icon` / `leftIcon` / `rightIcon` / `prefixIcon` / `suffixIcon` — slot or `string` (icon name); see slot guidance below
    - `items` / `options` / `actions` / `links` — usually array content; if the element shape is simple, classify as `string` (comma-separated names/IDs) and note in `description`. Only exclude when elements are deep nested objects with no flat representation.
@@ -163,10 +263,25 @@ For each `RawPropDefinition`, apply in order:
    - `accessibleNameRef` / `accessibleDescriptionRef` (web components) — these are ID references for a11y wiring; classify as `string`, `cdf_category: "state"` (behavioral wiring, not design or content).
    - `eventDetails` / similar telemetry props — `cdf_category: "state"`.
 3. **Positional/geometric design prop?** (`top`, `bottom`, `left`, `right`, `rotation`, `offset`, `zIndex`) → `classify_prop`, `cdf_type: "string"`, `cdf_category: "design"`.
-4. **Has `tokenReference`?** → `cdf_type: "token"`, resolve `token_kind` via sidecar lookup (see below). This overrides all other heuristics.
-5. **Union of string literals** (e.g. `'a' | 'b' | 'c'`)? → `cdf_type: "enum"`, extract literals into `values`.
+4. **`enum` or `token`? — run the three-question procedure first.** Before any type-based rule, for every design prop that carries a value, answer Q1–Q3 from "`enum` versus `token`" above, in order, from the source shown:
+
+   * **Q1** looked up / switched on / compared / has its own vocabulary → `cdf_type: "enum"`, names in `values`, no `token_kind`. This holds even when every name maps 1:1 to a design token; the map is the component resolving a name it was given.
+   * **Q2** not written straight into a style or attribute → not `token`; continue to rules 5–7.
+   * **Q3** written straight into a style or attribute **and** a token reference at that use (a `tokens.*` parameter default, a `tokenReference`, an inline `tokens.*` / `var(--*)`) → `cdf_type: "token"`, `token_kind` from that reference via the sidecar, no `values`. Interpolated with no token reference at that use → `cdf_type: "string"`.
+   * Q1–Q3 **cannot be answered** from the source shown (unread, truncated, in a file you cannot see, evidence pointing both ways) → `cdf_type: "enum"` (or `string`). See "Ambiguity resolves to `enum`" above.
+
+   **Do not classify on the component's role.** A layout primitive is not automatically a token consumer. Design systems routinely key their primitives on token *names*, and those props are `enum` — the component needs the name to perform its own lookup:
+
+   ```ts
+   // Box.tsx — padding is an enum, despite Box being a layout primitive
+   const { padding } = props;                  // "spacingXs"
+   getSpacingStyles({ padding });               // → SpacingTable["spacingXs"] → "0.5rem"
+   ```
+
+   Classify that `padding` as `token` and the platform delivers `"0.5rem"`, so `SpacingTable["0.5rem"]` is `undefined` and the spacing silently disappears. A value that is spelled like a token name is still a lookup key (Q1 yes). Curated components with named variant APIs (`Button`, `Tag`, `Badge`, `Avatar`, `Notification`) are `enum` for the same reason. A design system may legitimately produce **zero** token-typed props.
+5. **Union of string literals** (e.g. `'a' | 'b' | 'c'`)? → `cdf_type: "enum"`, extract literals into `values`. (Rule 4's Q1 will normally have decided this already — a literal union is the prop's own vocabulary.) This applies even when Component source references show each literal resolving to a design token internally — a resolved token map is evidence about the component's internals, not its interface.
 6. **Raw type is `string`** and prop name is `href`, `url`, or clearly a URL? → `cdf_type: "string"`, `cdf_category: "content"`.
-7. **Raw type is `string` / `number` / `boolean`?** → For `boolean`, use `cdf_type: "boolean"` with `default: true` or `false` (native boolean). For `number`, use `cdf_type: "string"` with `default` as the numeric value as a string (e.g. `"0"`). For `string`, use `cdf_type: "string"`.
+7. **Raw type is `string` / `number` / `boolean`?** → For `boolean`, use `cdf_type: "boolean"` with `default: true` or `false` (native boolean). For `number`, use `cdf_type: "string"` with `default` as the numeric value as a string (e.g. `"0"`). For `string`, use `cdf_type: "string"`. **A design prop reaches this rule only after leaving rule 4 at Q2 (not written into a style) or Q3 (written into a style with no token reference at that use).** A prop that answered Q3 yes is already `token` and never arrives here — a `string`, `number`, or `string | number` annotation on it does not bring it back to this rule.
 8. **Media/image type** (`ImageProps`, `MediaSource`, asset types)? → `cdf_type: "media"`.
 9. **Rich text / markup** (`ReactNode` used as content, HTML string)? → `cdf_type: "richtext"`.
 10. **Complex type — resolve before excluding** (see below).
@@ -182,8 +297,8 @@ A prop with a complex TypeScript type is **not automatically excluded**. Many pr
 | Raw type pattern | How to resolve |
 |---|---|
 | `'primary' \| 'secondary' \| 'ghost'` (union of literals) | → `enum`, extract `values` |
-| `HeadingSize` / `ButtonVariant` / any named type that is clearly a finite set of visual options | → `enum`, infer likely values from the prop name and context (e.g. `['sm', 'md', 'lg']` for size, `['primary', 'secondary']` for variant). Document your inference in `description`. |
-| `Variant` / `variant` prop | Usually a visual design variant. → `enum`, `cdf_category: "design"`. Infer values from context. |
+| `HeadingSize` / `ButtonVariant` / any named type that is clearly a finite set of visual options | → `enum`. **Never invent a value list.** Use only values you can cite from the source shown (the type's own declaration, a lookup table, a default). If the source shown does not enumerate the values, this is the "cannot be answered" case — apply "Ambiguity resolves to `enum`": emit `enum` (or `string` if it has no discoverable value set) and record the missing evidence in `description` (not `reason` — `description` ships to the CDF, `reason` does not), e.g. `"WARNING: values not visible in source — enum values unconfirmed"`. Do not default to a generic guess like `['sm', 'md', 'lg']` or `['primary', 'secondary']` — those are one design system's vocabulary, not a fallback for missing evidence. |
+| `Variant` / `variant` prop | Usually a visual design variant. → `enum`, `cdf_category: "design"`. Same evidence rule as above — cite values from the source shown; do not invent them. |
 | `Section[]` / array of custom items where the structure is unclear | → `exclude_prop` only if the array elements are complex objects with no obvious flat representation. If items are simple (title, label, id), consider representing as `string` (a comma-separated IDs or keys) or note in `description` why. |
 | `ExperienceConfiguration<Variant>` / deep generic | Personalization config — → `exclude_prop`, reason: `"personalization configuration — framework internal"` |
 | `React.Dispatch<...>` / setter | State setter — → `exclude_prop`, reason: `"React state setter — framework internal"` |
@@ -233,26 +348,20 @@ Rules for nested objects:
 
 ---
 
-## Token-aware mapping
+## Resolving `token_kind`
 
-When `tokenReference` is present, classify with `cdf_type: "token"`. The `token_kind` field becomes `$token.kind` in the CDF output (a DTCG `$type` string, e.g. `"color"`).
+`token_kind` becomes `$token.kind` in the CDF output — the DTCG `$type` of the token the prop binds to. For a prop that earned `cdf_type: "token"` (Q2 yes, Q3 yes), take the token name cited at Q3 (`tokens.borderRadiusSmall`, `var(--brand-primary)`, a raw `tokenReference`) and resolve it against the inline token data: through the token-name sidecar (raw name → DTCG dot-notation path) when one is provided, otherwise by matching the name to the DTCG tree by spelling (`tokens.borderRadiusSmall` → `border-radius.border-radius-small`); the leaf's `$type` (`"dimension"`) is the `token_kind`. If the name cannot be resolved to a leaf, keep `cdf_type: "token"`, omit `token_kind`, and say so in `description` (`"WARNING: token_kind unknown — <name> not found in token data"`).
 
-1. Look up `tokenReference` in the inline token-name sidecar → get the DTCG dot-notation path
-2. Traverse that path in the inline DTCG token data to reach the leaf token
-3. Use the leaf's `$type` (e.g. `"color"`) as `token_kind`
+**Canonical example — a named variant backed by tokens is still `enum`:**
 
-Example:
 ```
-tokenReference: "--brand-primary"
-  → sidecar["--brand-primary"] → "colors.brand.primary"
-  → token data: colors.brand.primary.$type → "color"
-  → tool call: {"tool":"classify_prop","prop":"bgColor","cdf_type":"token","cdf_category":"design","token_kind":"color","description":"..."}
+Tag.variant has allowedValues ["primary","secondary","warning","negative"] and PillNext.styles.ts
+maps each one to a token (primary→tokens.blue100, warning→tokens.orange100, ...). The mapping is
+internal to the design system — Tag's prop signature accepts the name, not the token. Classifying
+as enum so the author picks "primary" and the component receives "primary".
+{"tool":"classify_prop","prop":"variant","cdf_type":"enum","cdf_category":"design","required":false,"values":["primary","secondary","warning","negative"],"default":"primary","description":"Visual variant","reason":"Fully token-backed internally, but the component consumes the variant name. Token classification would deliver a resolved color the component cannot branch on."}
 ```
 
-If `tokenReference` is not found in the sidecar → `cdf_type: "token"`, omit `token_kind`, add `description: "WARNING: tokenReference not found in sidecar — token_kind unknown"`.
-
-If token data was not provided and `tokenReference` is present → `cdf_type: "token"`, omit `token_kind`, add `description: "WARNING: no token data supplied — token_kind unknown"`.
-
 ---
 
 ## Category correction rules
@@ -261,7 +370,7 @@ The pre-classified `category` is wrong in predictable ways. Correct silently (do
 
 - Visual style props (`color`, `size`, `padding`, `spacing`, `variant`, `theme`, `bgColor`, `imageOnLeft`, `enableXxx`) classified as `content` or `state` → `design`
 - Interactive/behavioral state props (`disabled`, `loading`, `expanded`, `selected`, `checked`, `active`, `isOpen`, `isSearchVisible`, `showXxx`, `hideXxx`, `preview`, `componentId`, `sectionKey`, `variantIndex`) classified as `design` or `content` → `state`
-- Text/label/data props (`title`, `label`, `description`, `caption`, `text`, `boldText`, `labelText`, `richText`, `backgroundImage`, `link`, `placeholder`, `searchValue`, `total`, `slug`) classified as `design` → `content`
+- Text/label/data props (`label`, `description`, `caption`, `text`, `boldText`, `labelText`, `richText`, `backgroundImage`, `link`, `placeholder`, `searchValue`, `total`, `slug`) classified as `design` → `content`. `title` is excluded from this auto-correction — it is one of the most common HTML-inherited attribute names (see the pass-through principle above). Only apply this correction to a `title` prop the component redeclares with its own type or documented, component-specific meaning; a `title` that is bare inherited pass-through was already excluded in rule 1 and never reaches this step.
 - Locale classified as `content` → `state` (it is a behavioral routing value, not editor-filled text)
 
 > **Key question for category**: "Who fills this in?" — A content editor fills in `content`. A designer configures `design`. Neither fills in `state` — it comes from routing, runtime behavior, or component infrastructure.
@@ -363,13 +472,6 @@ inferring likely values: ["h1", "h2", "h3", "h4", "h5", "h6"] — documenting in
 {"tool":"classify_prop","prop":"titleSize","cdf_type":"enum","cdf_category":"design","required":false,"values":["h1","h2","h3","h4","h5","h6"],"description":"Heading level — inferred from HeadingSize type name; actual values may be h1–h6 or sm/md/lg"}
 ```
 
-### Token-linked prop
-
-```
-bgColor has tokenReference "--bg-primary" — looking up sidecar
-{"tool":"classify_prop","prop":"bgColor","cdf_type":"token","cdf_category":"design","token_kind":"color","description":"Background color token linked via --bg-primary → colors.bg.primary"}
-```
-
 ### href prop
 
 ```
@@ -383,7 +485,6 @@ href is a URL string — cdf_type string (not link), category content
 
 - **Prop with unresolvable type** (generics, intersection, callback) → `exclude_prop` with reason `"complex type — not representable in CDF"`.
 - **Component with zero classified props after exclusions** → still emit `classify_component`. The DB entry will have an empty `$properties` object.
-- **tokenReference present but not in sidecar** → `cdf_type: "token"`, omit `token_kind`, add `description` warning.
 - **Slot not in DB** → skipped with a warning; does not abort the run.
 - **Prop not in DB** → skipped with a warning; does not abort the run.
 
@@ -395,15 +496,18 @@ Before emitting any tool calls, verify:
 2. Every slot has exactly one `classify_slot` call
 3. `classify_component` is emitted exactly once
 4. Every `cdf_type: "enum"` has a non-empty `values` array
-5. Every `cdf_type: "token"` has `token_kind` (or a warning in `description` if lookup failed)
+5. Every `cdf_type: "token"` has `token_kind` (or a warning in `description` if lookup failed) and does **not** have `values` set
 6. No `cdf_type: "link"` — all href/url props use `string`
 7. `required` values are JSON booleans, not strings
-8. Framework, DOM, accessibility, and data-* pass-through props are excluded — `className`/`classes`/`classNames`/`rootClassName`/`prefixCls`, `style`, `id`, `role`, `tabIndex`, `aria-*` (and bare `aria`), `data-*`, polymorphic `as`/`element`/`component`, framework theming `dt`/`pt`/`ptOptions`/`unstyled`/`sx`. Discrete positional/geometric props (`top`, `bottom`, `left`, `right`, `rotation`, etc.) ARE classified as `string` design props. Common semantic props (`icon`, `items`, `actions`, `options`, `value`, `name`, `form`, `inputId`, `componentId`) are NOT excluded — classify them per their content/design/state nature.
+8. Framework, DOM, accessibility, and data-* pass-through props are excluded per the inheritance principle (rule 1) — any prop inherited from an HTML-attributes base interface and not redeclared by the component, plus `aria-*` (and bare `aria`), `data-*`, polymorphic `as`/`element`/`component`, framework theming `dt`/`pt`/`ptOptions`/`unstyled`/`sx`. A prop matching an inherited-attribute name (including `title`) that the component redeclares with its own type or meaning is NOT excluded. Discrete positional/geometric props (`top`, `bottom`, `left`, `right`, `rotation`, etc.) ARE classified as `string` design props. Common semantic props (`icon`, `items`, `actions`, `options`, `value`, `name`, `form`, `inputId`, `componentId`) are NOT excluded — classify them per their content/design/state nature.
 9. No `cdf_type: "link"` used — `link` is reserved and rejected by the CLI parser
 10. No `cdf_type: "number"` used — this is not a supported type; use `"string"` with numeric defaults. `cdf_type: "boolean"` IS valid — use it for boolean toggle props.
 11. `classify_component` includes a `rationale` object with all three sub-fields (`rationale.description`, `rationale.props`, `rationale.slots`) populated as non-empty strings.
 12. Every `classify_slot` includes a non-empty `rationale` string.
 13. `rationale.description` follows the same "Description content rules" as `description` — no internal initiative names (`INTEG-*`, `EDSI`, `DSI`, `M1`, `M2`, wave/phase references, etc.).
+14. Every `cdf_type: "token"` prop cites a line that interpolates its value into a style **and** a token reference at that use (Q2 yes, Q3 yes), and carries no `values`. If you cannot cite both, it is `enum` or `string`; if you can, it is `token` — its type annotation is not a reason to emit `string`.
+15. Every prop whose values are friendly names is `enum` with a non-empty `values` array, even when each name resolves to a design token internally; every prop for which Q1–Q3 could not be answered was emitted as `enum` (or `string`) with the ambiguity stated in `reason`, and no answerable prop was called ambiguous.
+16. Every `enum`'s `values` array is copied from evidence in the source shown (a type declaration, lookup table, or default) — none of it was invented. Where no evidence exists for the values, the `description` states so (e.g. `"WARNING: values not visible in source"`), not just `reason`.
 
 After the run completes, the developer can validate the pipeline output with:
 

package/skills/map-tokens.md

@@ -0,0 +1,90 @@
+# Map Tokens — Token Restriction Narrowing Skill
+
+## Purpose
+
+For every design-category, token-typed prop already present in the generated CDF, decide whether there is concrete evidence to narrow it to a restricted subset (`$token.allowed`). Output one JSON tool call per line to stdout — the CLI reads it and writes each decision directly to the pipeline database. You do not write any files.
+
+This is a narrowing fallback, not a classification step: it does not re-classify props or touch anything that isn't already a design-category `token` prop. It also does not name a candidate universe — the universe is implicit, every token in the library whose type matches the prop's `$token.kind`. Your only job is to decide, from source evidence, whether that universe should be narrowed further.
+
+Default-path resolution is deterministic and happens in the CLI before this skill runs. A resolved `$default` is not model input for a mapping decision and never asks you to emit a mapping — a default alone does not restrict the allowed list.
+
+---
+
+## Input
+
+All input is embedded inline in the prompt before this file:
+
+- **Generated CDF so far** — design-category, token-typed props only, grouped by component. Every prop shown here already has `$type: "token"` and `$category: "design"`; you do not need to re-verify either.
+- **Token path index** — one or more sections, each a flat list of `path · type` lines (one leaf token per line, `$value` omitted). Every section is pre-scoped: a section titled with a `$token.kind` contains every leaf token of that type and no others; a prop with that `$token.kind` draws its candidates only from the matching section. The "full tree" section — present only when at least one prop has no `$token.kind` — lists every leaf token, unscoped. Never mix candidates across sections.
+- **Component source references** — the real file text for each component (bounded/truncated), rendered inline as a fenced code block, so you can look for an explicit restriction: a comment naming the valid tokens, or code that validates the prop against a fixed list of token paths. Content from files the component's own file imports (siblings) is inlined the same way, one hop deep — token-resolution logic often lives one file away from the component itself. When more sibling files were found than could be inlined, or a property has a use that fell outside the excerpt shown, the prompt says so explicitly; treat that as unknown evidence, not absence. **You have no filesystem access and no tools — a citation path is a label only, never something to open.** When a component's source couldn't be read (moved/deleted since extraction), there is no source evidence to narrow from — skip the prop.
+
+If no token path index is provided, there is nothing to narrow against — do not emit any tool calls.
+
+---
+
+## Decision tree
+
+For each design-category, token-typed prop shown in the "Generated CDF so far" section:
+
+1. **Prop type is a union of variant names** (e.g. `'primary' | 'secondary'`)? That prop should not be a `token` at all — the component receives a name and resolves it, which is the `enum` case in the classification step. Do not narrow it; narrowing cannot repair a wrong type. Emit nothing, and note in a prose line that it looks misclassified.
+2. **A default value or `tokenReference` is the prop's default, not a restriction.** `padding = tokens.spacingM` or a structured `tokenReference` tells you which token the prop *starts* on — it does not say the author may choose no other. Narrowing to that single path would leave the marketer one option, which is worse than no list. On its own, this evidence yields no tool call. If you narrow on other grounds (step 3), the default's path must be in the list.
+3. **Look for an explicit restriction** in the component source or its siblings: a comment naming the valid tokens, or code that validates/maps the prop against a fixed list of token paths (an allowlist array, a `satisfies` over specific token keys). If found, emit `$token.allowed` as the evidenced subset, scoped to tokens of the prop's `$token.kind`.
+4. **No explicit restriction?** Emit nothing. Omitting the list means "any token of this kind," which is correct and live — a guessed list is worse than none because it freezes the author's choices.
+5. **No plausible candidates at all** (no index entries of the prop's `$token.kind`)? Skip the prop.
+
+---
+
+## Output protocol
+
+Emit one JSON object per line. The CLI parses lines starting with `{`; anything else is prose, ignored by the parser — use it freely for reasoning.
+
+```
+{"tool":"map_token_prop","component":"<ComponentName>","prop":"<propName>","token_allowed":["colors.brand.primary","colors.brand.secondary"]}
+```
+
+Rules:
+
+- Emit exactly one JSON object per line. No multi-line JSON.
+- Only emit a call for a prop that appears in the "Generated CDF so far" section.
+- `token_allowed` is required and must be non-empty. If there's nothing to narrow to, emit no call at all.
+- Every path in `token_allowed` must be an individual **leaf** path that exists verbatim in the token path index section matching the prop's `$token.kind` (or the "full tree" section, for a prop with no `$token.kind`). Never emit a group/prefix path (e.g. `colors.brand`) — the index has no entry for groups, only leaves. Never invent a path, and never substitute a variant/enum name for a real token path; if you can't find a matching path, omit that entry.
+- No `$value` is provided in this step — reason from paths and `$type` only.
+
+---
+
+## Examples
+
+### Explicit restriction — narrow
+
+```ts
+interface ButtonProps {
+  /** Accepts only the brand colour tokens: colors.brand.primary or colors.brand.secondary. */
+  accentColor?: string;
+}
+const ACCENT_TOKENS = ['colors.brand.primary', 'colors.brand.secondary'] as const;
+```
+
+```
+accentColor is restricted to two named tokens by the doc comment and the ACCENT_TOKENS allowlist
+{"tool":"map_token_prop","component":"Button","prop":"accentColor","token_allowed":["colors.brand.primary","colors.brand.secondary"]}
+```
+
+### No restriction evidence — emit nothing
+
+`bgColor` is interpolated generically, with no comment or allowlist naming specific tokens, and no default. Any color token remains valid:
+
+```
+bgColor has no restriction evidence in source — any color token remains valid, so no tool call
+```
+
+---
+
+## Checklist
+
+Before emitting any tool calls, verify:
+
+1. Every `map_token_prop` call targets a prop that appears in the "Generated CDF so far" section.
+2. Every path in `token_allowed` is a leaf path that exists verbatim in the token path index, and matches the prop's `$token.kind` — no group/prefix paths, no variant names, nothing invented.
+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.