dt-use-existing-component

name: dt-use-existing-component description: >- Find and reuse existing @dt design-system components before creating new UI. Use when the user asks which component to use, wants to avoid duplicating UI, needs import guidance, or says "reuse component", "what should I use for", "find component", "dogfood audit", or "existing primitive for". metadata: version: 1.0.0 category: design-system

Reuse existing @dt components

Rule

Search the catalog before creating UI. Digitaltableteur is AI-readable but not yet AI-native — contracts validate governance; usage evidence tells you what is proven in production.

Step 1: Rank by intent

npm run find-component -- "dismissible warning banner with action"
npm run find-component -- --json "primary loading button"

Prefer matches with:

higher score
productionImportCount > 0
status: stable or beta over alpha

Step 2: Inspect manifest evidence

npm run build:tokens   # refreshes agent-manifest.json with usage scan
npm run audit:usage    # human-readable top consumers
npm run audit:usage -- --json

Open nextjs-app/shared/foundations/dist/agent-manifest.json:

usageCoverage — fleet-wide stats
components[].usage — publicImport, evidence[], import counts
components[].agent — generated props, variants, useWhen/avoidWhen, replacementFor

Or read component-agent-blocks.json directly after npm run build:agent-blocks.

Step 3: Read contract + spec

For the chosen component <Name>:

nextjs-app/shared/components/<Name>/<Name>.contract.json (or patterns/)
<Name>.spec.md — Intent, Do/don't, Interaction contract
<Name>.stories.tsx — canonical props (until prop schema is generated in contract v2)

Import policy: always @dt/<Name> — see docs/PUBLIC_API.md.

Step 4: Validate choice

npm run validate:components
npm test -- <Name>

If no catalog match fits, escalate to dt-design-system to scaffold — do not drop in raw <button>, headings, or shadcn duplicates.

Usage vs stable consumers

Field	Purpose
`manifest.components[].usage`	All statuses — auto-scanned import evidence for agents
`contract.consumers[]`	Stable promotion only — shipping-product proof

Do not treat empty consumers[] on beta components as "unused".

Anti-patterns

Raw <h1>–<h6>, <p>, styled <button> when Title, Text, Button exist
@/components/ui/* when an @dt/* equivalent exists
Hand-rolling layout spacing instead of Stack, Row, Grid, Container

dt-design-system — create/modify components
docs/PUBLIC_API.md — import surface and verification commands