component_map · Tools · OODS Foundry

Use it when connecting React/Vue exports or shadcn source to OODS components; use catalog_list to find component names. Returns entries, matches or per-entry write outcomes. action selects draft/show/apply/create/list/resolve/update/delete. draft reads local shadcn or built Storybook files without executing code; show exposes evidence, adapter files and unmatched elements; apply with draftId and accept ids validates and atomically registers reviewed mappings. create accepts a single entry, mappings list or mappingsPath; lists validate completely before one write. substitution supplies exports and prop translations with exact package versions or installed localPath. React/Vue shadcn mappings use an installed project and module instead. Compose snapshots mappings; generation/preview apply them. apply controls mutation where supported. Reference: TOOL-REFERENCE.md#component_map; full schema: oods://schemas/component_map.input.json.

Inputs

Name	Type	Required	Description
`action`	`"apply" \| "create" \| "list" \| "resolve" \| "update" \| "delete" \| "draft" \| "show"`	yes	Selects the per-action handler to invoke.
`apply`	`boolean`	no	For apply: When true, persist registry mutations. Actions: apply, create, list, resolve, update, delete. See full schema for details.
`minConfidence`	`number`	no	Candidates below this threshold are routed to queued instead of being applied. Actions: apply.
`reportPath`	`string`	no	Filesystem path to a reconciliation_report.json artifact. Actions: apply.
`report`	`object`	no	Reconciliation report. Actions: apply.
`mappings`	`object \| array \| string \| number \| boolean \| null[]`	no	Create entries, each without apply. All entries are checked before one atomic write. Actions: create.
`mappingsPath`	`string`	no	Absolute path to a JSON document { mappings: [...] }, using the same entry shape. Actions: create.
`substitution`	`object`	no	Version 2 component substitution: an OODS Foundry id, React and/or Vue package exports, and OODS Foundry-to-team prop translations. Legacy trait-only mappings remain valid. Actions: create.
`externalSystem`	`string`	no	For create: External design system name (for example, 'team'). Actions: create, list, resolve (required), draft. See full schema for details.
`externalComponent`	`string`	no	For create: Component name in the external system (e.g., 'Button', 'TextField'). For resolve: Component name in the external system (e.g., 'Button'). Actions: create, resolve (required).
`oodsTraits`	`string[]`	no	OODS trait names this component maps to. Actions: create.
`propMappings`	`object[]`	no	Property translations from external to OODS prop names. Actions: create.
`confidence`	`"auto" \| "manual"`	no	'auto' for machine-generated, 'manual' for human-curated. Actions: create.
`metadata`	`object`	no	Mapping metadata. Actions: create.
`disambiguation_decisions`	`object[]`	no	Draft v1.4.0-gated review-decision events to APPEND to the registry's top-level disambiguation_decisions[]. Additive stub only; does not gate mapping creation. Each entry uses the Stage1 disambiguation_decision shape. Actions: create.
`preferred_terms`	`object[]`	no	Draft v1.4.0-gated canonical-term entities to APPEND to the registry's top-level preferred_terms[]. Each entry uses the Stage1 preferred_term entity shape. Actions: create.
`capabilities`	`object[]`	no	Draft v1.4.0-gated first-class capability entities to APPEND to the registry's top-level capabilities[]. Each entry uses the Stage1 capability entity shape. Actions: create.
`projection_variants`	`object[]`	no	Stage1 v1.5.0 cross-surface identity variants. Each element describes one surface-specific projection of this component mapping (desktop/mobile/modal/sidebar). Actions: create.
`cursor`	`string`	no	Pagination cursor. Use the previous page's nextCursor to continue. When cursor or limit is provided, pagination defaults to 100 items per page. Actions: list.
`limit`	`integer`	no	Page size for pagination. Omitting both cursor and limit preserves the legacy full-list response. Actions: list.
`id`	`string`	no	For update: Mapping ID to update (e.g., 'team-button'). For delete: Mapping ID to delete (e.g., 'team-button'). Actions: update (required), delete (required).
`updates`	`object`	no	Fields to update. Only provided fields are changed. Actions: update (required).
`source`	`object`	no	Actions: draft (required).
`draftId`	`string`	no	Actions: show (required), apply (required).
`accept`	`string[]`	no	Actions: apply (required).

Outputs

The package ships no output schema for this tool.

A real call

Recorded by this site's harbor run, step mapping, with the published OODS Foundry 0.10.1.

Its input:

{
  "action": "create",
  "apply": true,
  "externalSystem": "harbor",
  "externalComponent": "TeamButton",
  "oodsTraits": [
    "Stateful"
  ],
  "substitution": {
    "component": "Button",
    "react": {
      "package": "@harbor/example-components/react",
      "version": "1.0.0",
      "export": "TeamButton",
      "localPath": "<workspace>/harbor-design-system/team-components",
      "props": {
        "content": {
          "name": "caption"
        },
        "intent": {
          "name": "appearance",
          "values": {
            "neutral": "quiet",
            "primary": "prominent",
            "danger": "danger"
          }
        }
      }
    },
    "vue": {
      "package": "@harbor/example-components/vue",
      "version": "1.0.0",
      "export": "TeamButton",
      "localPath": "<workspace>/harbor-design-system/team-components",
      "props": {
        "content": {
          "name": "caption"
        },
        "intent": {
          "name": "appearance",
          "values": {
            "neutral": "quiet",
            "primary": "prominent",
            "danger": "danger"
          }
        }
      }
    }
  }
}

Its result:

{
  "status": "ok",
  "mapping": {
    "id": "harbor-team-button",
    "externalSystem": "harbor",
    "externalComponent": "TeamButton",
    "oodsTraits": [
      "Stateful"
    ],
    "substitution": {
      "component": "Button",
      "react": {
        "package": "@harbor/example-components/react",
        "version": "1.0.0",
        "export": "TeamButton",
        "localPath": "<workspace>/harbor-design-system/team-components",
        "props": {
          "content": {
            "name": "caption"
          },
          "intent": {
            "name": "appearance",
            "values": {
              "neutral": "quiet",
              "primary": "prominent",
              "danger": "danger"
            }
          }
        },
        "passthrough": true
      },
      "vue": {
        "package": "@harbor/example-components/vue",
        "version": "1.0.0",
        "export": "TeamButton",
        "localPath": "<workspace>/harbor-design-system/team-components",
        "props": {
          "content": {
            "name": "caption"
          },
          "intent": {
            "name": "appearance",
            "values": {
              "neutral": "quiet",
              "primary": "prominent",
              "danger": "danger"
            }
          }
        },
        "passthrough": true
      }
    },
    "confidence": "manual",
    "metadata": {
      "createdAt": "2026-10-08T15:03:14.052Z"
    }
  },
  "etag": "3634e3e2a0e04df032fea58aad304694e5a16042f24b5d02db92417001787fc7",
  "applied": true
}

The whole call, 3 KB of JSON