---
prompt-id: "26"
name: Legacy component refactor — to archetype spec
status: live
mcp: optional (Figma reference if exists)
model: Sonnet 4.6
environment: Claude Code (file modification)
inputs:
  - Legacy component code
  - Archetype name
  - governance.spec.md
  - [archetype].spec.md
  - tokens.css
outputs:
  - Refactored component (drop-in replacement, behavior identical)
  - Diff summary (banned removed, governance applied, tokens swapped)
  - Test plan (which props/states to verify)
  - Optional deprecation shim for renamed props
chains: []
prereqs: []
documented-in: Ch18 — Figma → Code (Legacy refactor section)
---

# Prompt 26 — Legacy Component Refactor

The component shipped before the spec existed. It works in production, but it doesn't follow the archetype's banned patterns, governance rules, or token naming. This prompt refactors it into compliance without changing behavior. The output is a drop-in replacement that passes Chain 4 (drift audit) and Chain 5 (a11y audit) — and preserves the exact prop API so consumers don't break.

## When to use

Brownfield system adoption. You have an existing codebase that predates your archetype spec, and you need to bring components into compliance one at a time. Run per-component, not bulk. Pair with Chain 4 + Chain 5 after each refactor to confirm the result.

## Output shape

Four artifacts:
1. **Refactored component** — drop-in replacement, identical behavior
2. **Diff summary** — what was banned (removed/replaced), what governance was applied, which raw values became tokens
3. **Test plan** — which props and states to exercise post-refactor
4. **(Optional) Deprecation shim** — if any prop renames are unavoidable, a compatibility shim for one MINOR version

## Chain memberships

- None directly. Refactor outputs are validated by Chain 4 (drift audit) and Chain 5 (a11y audit) which are the actual gates.

## Prompt body

```
Refactor this legacy component to comply with the archetype spec.
The behavior must stay identical — only the implementation changes.

Legacy component: [paste source code]
Archetype: [Harbor | Sentinel | Current | Lattice | Meridian]
Specs (paste both):
  governance.spec.md: [paste]
  [archetype].spec.md: [paste]
Token system: src/tokens.css (paste)

Refactor rules:
1. Replace every raw value with the matching token from tokens.css.
   If no matching token exists, propose a new one and add it inline.
2. Apply the archetype's banned patterns list — anything banned that
   the legacy code uses must be removed and replaced.
3. Apply governance state coverage: every interactive element must
   have default / hover / focus-visible / active / disabled.
4. Apply governance copy hygiene: remove "Please", marketing fluff,
   "Submit"/"OK" buttons, etc.
5. Apply ARIA correctness — aria-label on icon buttons, aria-expanded
   on disclosure widgets, aria-live for async messages.
6. Keep the prop API EXACTLY as it was — consumers must not break.

Output:
- The refactored component (drop-in replacement)
- A diff summary: what was banned, what was added, what was renamed
- A short test plan: which props/states to verify post-refactor
- A note on whether prop renames are needed (if so, provide a
  deprecation shim so the old API works for one MINOR version)

Run Chain 4 (drift audit) and Chain 5 (a11y audit) after refactor.
Both must pass with zero Critical findings before merging.

META-FOOTER (chain runner)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MCP OPTIONAL
  Connect Figma if a canonical version of the component exists.
  Sonnet 4.6 · Claude Code · per-component pace.

SAVE INSTRUCTION
  Replace the legacy file in output/components/
  Keep original in output/components/_archive/<date>/<ComponentName>/

VERIFY
  Chain 4 (drift audit) returns zero Category A findings.
  Chain 5 (a11y audit) returns zero Critical findings.
  Prop API unchanged — consumer code compiles without changes.

HANDOFF
  "Refactor complete. Diff summary in output/refactor-notes.md.
   Run Chain 4 + Chain 5 — both must pass before merge.
   If prop renames were unavoidable, ship the deprecation shim
   for one MINOR version, then remove in next MAJOR."
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```