Tools Reference

All tools are detector-only — they report, never write source, config, or anything outside .dna/. The calling agent uses the findings to make its own edits with its own tools.

dna_check

Run DNA's design-system conformance check.

Parameters:

Parameter	Type	Default	Description
`audit`	boolean	`true`	`true` = whole-repo scan. `false` = only changed lines since `base`.
`base`	string	`HEAD`	Git ref to diff against when `audit` is `false`.
`cwd`	string	workspace root	Absolute path to the project root.

Returns:

{
  "status": "fail",
  "mode": "audit",
  "summary": { "errors": 2, "warnings": 0 },
  "findings": [
    {
      "rule": "color-family-allowlist",
      "severity": "error",
      "file": "src/components/Button.module.css",
      "line": 14,
      "value": "rgba(182, 141, 66, 0.1)",
      "snippet": "background: rgba(182, 141, 66, 0.1);",
      "hint": "use var(--brand)"
    }
  ]
}

The payload also folds in the optional render / figma sub-checks (rendered conformance, structural manifests) when those peers are installed and configured — matching the CLI's own dna check behavior. It may include a staleness note when the identity is older than recent commits that touched checked source.

When to call it: After editing any design-relevant file (styles, tokens, component markup). The cooperation convention in CLAUDE.md/AGENTS.md instructs agents to call this automatically.

dna_resolve

Reverse-lookup a raw design value to the project's identity token(s) — the proactive counterpart to dna_check.

Parameters:

Parameter	Type	Description
`value`	string	A color (`#2E7D32`, `rgb()`/`rgba()`) or a length (`16px`, `1rem`).
`cwd`	string	Absolute path to the project root (optional).

Returns: the matching token name(s) labeled by axis. A value on multiple scales (e.g. both a spacing step and a radius step) reports all of them, never one.

{
  "status": "resolved",
  "matches": [
    { "token": "--brand", "axis": "color" }
  ]
}

Tri-state and honest: resolved, not-a-token (well-formed but not in the identity — no green tick), no-identity, or invalid.

When to call it: Before writing a raw literal pulled from a design or frame — so the agent authors with the token instead of a hardcoded value that dna_check would flag afterward.

dna_inventory

Return the current component inventory parsed from code.

Parameters:

Parameter	Type	Default	Description
`cwd`	string	workspace root	Absolute path to the project root.

Returns:

{
  "status": "report",
  "count": 8,
  "components": [
    {
      "name": "Button",
      "props": ["variant", "size", "disabled", "onClick", "children"],
      "useWhen": "Primary action. Use for all form submissions and primary CTAs.",
      "path": "src/components/Button.tsx"
    }
  ]
}

When to call it: Before creating a new component. For components, the failure mode is ignorance — an AI rebuilds a Card not because it was told to, but because it never checked.

dna_similar

Run DNA's structural duplication check. Findings are tagged with kind:

"rebuild" — a hand-rebuild of an existing component: file, line, matched component name/path, score
"clone" — a net-new shape repeated across files with no backing component: size and the list of occurrences to extract

Parameters:

Parameter	Type	Default	Description
`audit`	boolean	`true`	`true` = whole repo. `false` = changed/untracked files only.
`base`	string	`HEAD`	Git ref for diff when `audit` is `false`.
`cwd`	string	workspace root	Absolute path to the project root.

Returns:

{
  "status": "report",
  "findings": [
    {
      "kind": "rebuild",
      "file": "src/screens/Dashboard.tsx",
      "line": 42,
      "matchedComponent": "Card",
      "matchedPath": "src/components/Card.tsx",
      "score": 0.91
    },
    {
      "kind": "clone",
      "occurrences": ["src/screens/Pricing.tsx:18", "src/screens/Landing.tsx:74"],
      "size": 14
    }
  ]
}

When to call it: Alongside dna_inventory before writing new component code. It catches reinvention that slips past a name-only check — and net-new shapes being cloned across files. Advisory, never gating.

dna_start_preview

Preview what dna start would extract and write — WITHOUT writing anything to disk.

Parameters:

Parameter	Type	Default	Description
`cwd`	string	workspace root	Absolute path to the project root.
`force`	boolean	`false`	Preview as if `--force` were passed (show draft even when identity.yaml exists).

Returns: the palette (declared + observed-in-usage), type scale, spacing grid/scale, radius scale/idioms, Tailwind color families, and per-value provenance annotations — as structured data.

{
  "status": "preview",
  "palette": {
    "brand": { "value": "hsl(38 47% 48%)", "from": "code", "at": "2026-08-10" }
  },
  "scales": {
    "type": { "body": { "value": 14 }, "display-xl": { "value": 34 } },
    "spacing": { "value": 4 },
    "spacingScale": [4, 8, 12, 16, 24, 32],
    "radius": { "value": 4 }
  },
  "families": { "allowed": [] }
}

When to call it: To show a user what dna start is about to set up before they run it themselves. dna start (CLI, user-initiated) is the only thing that actually writes.