@contentful/experience-design-system-cli 2.27.5-dev-build-56846c8.0 → 2.27.5-dev-build-347f1b0.0

package/dist/src/lib/cli-errors.d.ts

@@ -0,0 +1,2 @@
+export declare function die(message: string): never;
+export declare function assertBinaryInPath(binary: string): Promise<boolean>;

package/dist/src/map-tokens/apply.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { MapTokenPropCall } from '@contentful/experience-design-system-generation';
+export interface ApplyMapTokenPropCallsResult {
+    applied: number;
+    warnings: string[];
+}
+/**
+ * Applies parsed `map_token_prop` calls to the session database. Each call is
+ * validated against session state — unlike parseMapTokenPropToolCallLines,
+ * which only checks the call's own shape — before any write happens.
+ */
+export declare function applyMapTokenPropCalls(db: DatabaseSync, sessionId: string, calls: MapTokenPropCall[], incomingWarnings: string[]): ApplyMapTokenPropCallsResult;

package/dist/src/map-tokens/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerMapTokensCommand(program: Command): void;

package/dist/src/map-tokens/resolve-defaults.d.ts

@@ -0,0 +1,31 @@
+/** A token default extracted from a design-category token property. */
+export interface RawDesignTokenDefault {
+    /** The source default, retained verbatim for persistence and review. */
+    rawDefault: string;
+    /** The property's expected DTCG token type. */
+    tokenKind: string | null;
+}
+/** The path and type of one DTCG token leaf. Values are intentionally absent. */
+export interface DTCGTokenLeaf {
+    path: string;
+    type: string;
+}
+export type UnresolvedTokenDefaultReason = 'no_match' | 'ambiguous' | 'type_mismatch';
+export interface UnresolvedTokenDefault {
+    rawDefault: string;
+    tokenKind: string | null;
+    reason: UnresolvedTokenDefaultReason;
+    candidatePaths: string[];
+    message: string;
+}
+export interface ResolveTokenDefaultsResult {
+    /** Exact source defaults mapped to their one compatible DTCG path. */
+    mappings: Record<string, string>;
+    diagnostics: UnresolvedTokenDefault[];
+}
+/**
+ * Resolves extracted source defaults without inspecting token values or changing
+ * the source defaults. A normalised leaf-key match is accepted only when it
+ * identifies exactly one leaf compatible with the property's token kind.
+ */
+export declare function resolveTokenDefaults(defaults: readonly RawDesignTokenDefault[], leaves: readonly DTCGTokenLeaf[]): ResolveTokenDefaultsResult;

package/dist/src/map-tokens/tui/MapTokensView.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+export interface MapTokensViewResult {
+    agent: string;
+    sessionId: string;
+    applied: number;
+    cached: boolean;
+}
+interface MapTokensViewProps {
+    result: MapTokensViewResult;
+    onExit: () => void;
+}
+export declare function MapTokensView({ result, onExit }: MapTokensViewProps): React.ReactElement;
+export {};

package/dist/src/print/command.d.ts

@@ -1,2 +1,11 @@
 import type { Command } from 'commander';
+export declare function rebuildDTCGTree(groups: Array<{
+    path: string;
+    $description?: string;
+}>, tokens: Array<{
+    path: string;
+    $type: string;
+    $value: unknown;
+    $description?: string;
+}>): Record<string, unknown>;
 export declare function registerPrintCommand(program: Command): void;

package/dist/src/runs/modify-launcher.d.ts

@@ -10,6 +10,8 @@ export type ModifyLauncherInput = {
      *  generated. Forwarded to the wizard so the modify entry pre-loads
      *  tokens alongside the extract/generate sessions. */
     tokenSessionId?: string | null;
+    /** Absolute path to the complete DTCG token catalog written for this run. */
+    tokensPath?: string | null;
     projectPath: string;
     savePath: string;
     entryStep: 'scope-gate' | 'final-review';

package/dist/src/session/db.d.ts

@@ -1,11 +1,11 @@
 import { DatabaseSync } from 'node:sqlite';
 import type { RawComponentDefinition } from '../types.js';
 import type { CDFComponentEntry, DTCGTokenEntry, DTCGTokenGroup } from '@contentful/experience-design-system-types';
-import type { ToolCall, TokenToolCall } from '@contentful/experience-design-system-generation';
+import type { ToolCall, TokenToolCall, ComponentSourceRef } from '@contentful/experience-design-system-generation';
 import type { ComponentTypeSummary } from '@contentful/experience-design-system-types';
 import type { SlotCycle, SlotEdge } from '../analyze/cycle-detection.js';
 export type StepStatus = 'pending' | 'complete' | 'failed' | 'interrupted';
-export type CommandName = 'analyze extract' | 'analyze select' | 'generate components' | 'generate tokens' | 'generate edit' | 'apply preview' | 'apply select' | 'apply push' | 'print components' | 'print tokens' | 'import';
+export type CommandName = 'analyze extract' | 'analyze select' | 'generate components' | 'generate tokens' | 'generate edit' | 'apply preview' | 'apply select' | 'apply push' | 'print components' | 'print tokens' | 'map tokens' | 'import';
 export interface SessionRow {
     id: string;
     name: string | null;
@@ -26,6 +26,30 @@ export interface StepRow {
 }
 export declare function getPipelineDbPath(): string;
 export declare function openPipelineDb(dbPath?: string): DatabaseSync;
+/** An exact source token reference paired with its canonical DTCG path. */
+export type RawTokenNamePaths = Record<string, string>;
+export type RawTokenNamePathSource = 'automatic' | 'manual';
+export interface RawTokenNamePath {
+    rawName: string;
+    path: string;
+    source: RawTokenNamePathSource;
+}
+/**
+ * Replaces the session's exact source-reference-to-DTCG-path sidecar.
+ * Source references are retained verbatim; normalisation belongs to the
+ * deterministic resolver, not to persistence or CDF emission.
+ */
+export declare function replaceRawTokenNamePaths(db: DatabaseSync, sessionId: string, tokenNamePaths: RawTokenNamePaths, source?: RawTokenNamePathSource): void;
+/** Loads the exact source-reference-to-DTCG-path sidecar for a session. */
+export declare function loadRawTokenNamePaths(db: DatabaseSync, sessionId: string): RawTokenNamePaths;
+export declare function loadRawTokenNamePathRows(db: DatabaseSync, sessionId: string): RawTokenNamePath[];
+/**
+ * Where a prop's token-path list came from. 'agent' is a map-tokens suggestion,
+ * which a later run of that step may revise. 'review' is a person's decision in
+ * the review editor, which a re-run must leave alone.
+ */
+export type RawPropTokenPathSource = 'agent' | 'review';
+export declare function replaceRawPropTokenPaths(db: DatabaseSync, sessionId: string, componentId: string, propName: string, paths: string[], source: RawPropTokenPathSource): void;
 export interface ApplyToolCallsResult {
     classified: number;
     excluded: number;
@@ -83,6 +107,8 @@ export type RawComponentWithId = RawComponentDefinition & {
     component_id: string;
 };
 export declare function loadRawComponents(db: DatabaseSync, sessionId: string, allowedNames?: Set<string>): RawComponentWithId[];
+export declare function loadComponentSourceRef(name: string, sourcePath: string, propNames?: string[]): Promise<ComponentSourceRef>;
+export declare function loadComponentSourceRefs(db: DatabaseSync, sessionId: string): Promise<ComponentSourceRef[]>;
 export declare function renameEmptySlots(db: DatabaseSync, sessionId: string, componentId: string, componentName: string, slotCount: number): {
     renames: Array<{
         oldName: string;
@@ -133,9 +159,10 @@ export declare function seedDefaultsFromChangedItems(db: DatabaseSync, sessionId
     proposed: object;
 }>): number;
 export declare function backfillUnclassifiedProps(db: DatabaseSync, sessionId: string): number;
+export type CacheEntityType = 'component' | 'token_set' | 'token_mapping';
 export interface CacheEntry {
     inputHash: string;
-    entityType: 'component' | 'token_set';
+    entityType: CacheEntityType;
     entityId: string;
     sourceSessionId: string;
     humanEdited: boolean;
@@ -145,9 +172,10 @@ export interface CacheEntry {
 }
 export declare function computeComponentInputHash(component: RawComponentWithId): string;
 export declare function computeTokenInputHash(rawTokenContent: string): string;
-export declare function lookupCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, promptHash?: string): CacheEntry | null;
-export declare function lookupCacheByEntity(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): CacheEntry | null;
-export declare function storeCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, sourceSessionId: string, humanEdited: boolean, promptHash?: string): void;
+export declare function computeMapTokensInputHash(db: DatabaseSync, sessionId: string, componentSourceRefs?: readonly ComponentSourceRef[]): string;
+export declare function lookupCache(db: DatabaseSync, inputHash: string, entityType: CacheEntityType, entityId: string, promptHash?: string): CacheEntry | null;
+export declare function lookupCacheByEntity(db: DatabaseSync, entityType: CacheEntityType, entityId: string): CacheEntry | null;
+export declare function storeCache(db: DatabaseSync, inputHash: string, entityType: CacheEntityType, entityId: string, sourceSessionId: string, humanEdited: boolean, promptHash?: string): void;
 export declare function storeScannedFiles(db: DatabaseSync, sessionId: string, filePaths: string[]): void;
 export declare function loadScannedFiles(db: DatabaseSync, sessionId: string): string[];
 export declare function storeSlotCycles(db: DatabaseSync, sessionId: string, cycles: Array<SlotCycle & {
@@ -161,6 +189,7 @@ export declare function clearSlotCycles(db: DatabaseSync, sessionId: string): vo
 export declare function markCacheHumanEdited(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): void;
 export declare function copyComponentFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string, componentId: string): void;
 export declare function copyTokensFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string): void;
+export declare function copyMapTokensFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string): number;
 export declare function getCliCacheVersion(): Promise<string>;
 export interface ExtractCacheEntry {
     filePath: string;

package/dist/src/session/source-excerpt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bounded source excerpts that keep the lines that matter.
+ *
+ * Head truncation of a styles module keeps its imports and top-level
+ * constants and drops the one line that decides a property's classification —
+ * the place the value is interpolated into a style. An excerpt built from
+ * windows around each property name's occurrences spends the same byte budget
+ * on that line instead.
+ */
+export interface SourceExcerpt {
+    content: string;
+    /**
+     * Names with at least one occurrence that did not fit in `content`. The
+     * reader cannot see that use, so its absence from the excerpt is a gap, not
+     * evidence. Empty when every occurrence is shown.
+     */
+    usesNotShown: string[];
+}
+/**
+ * Returns `text` whole when it fits `maxChars`. Otherwise returns windows of
+ * `contextLines` lines around every line that mentions one of `names`, merged
+ * where they overlap, in file order, until the budget is spent. With no
+ * occurrences at all it falls back to the head of the file.
+ */
+export declare function excerptAroundNames(text: string, names: string[], maxChars: number, contextLines?: number): SourceExcerpt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.27.5-dev-build-56846c8.0",
+  "version": "2.27.5-dev-build-347f1b0.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -39,7 +39,7 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.27.5-dev-build-56846c8.0"
+    "@contentful/experience-design-system-types": "2.27.5-dev-build-347f1b0.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
@@ -51,9 +51,9 @@
     "ink-testing-library": "^4.0.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.0.16",
-    "@contentful/experience-design-system-client": "2.27.5-dev-build-56846c8.0",
-    "@contentful/experience-design-system-extraction": "2.27.5-dev-build-56846c8.0",
-    "@contentful/experience-design-system-generation": "2.27.5-dev-build-56846c8.0"
+    "@contentful/experience-design-system-client": "2.27.5-dev-build-347f1b0.0",
+    "@contentful/experience-design-system-extraction": "2.27.5-dev-build-347f1b0.0",
+    "@contentful/experience-design-system-generation": "2.27.5-dev-build-347f1b0.0"
   },
   "repository": {
     "type": "git",

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.