Component Kit Consolidation

Component kit consolidation

0. Avoid needing this skill

This is the BROWNFIELD recovery method. For greenfield/rebuild work, do not plan to land here: converge a compact component kit BEFORE fanning out parallel scene agents (see /design-fidelity-loop phase 0, "kit first"). Scene lanes then compose kit components and request additions instead of defining their own — and the ~50-divergent-copies problem this skill exists to clean up never happens. Use the rest of this skill when you inherited a scenes-first codebase.

Method for collapsing N hand-rolled copies of the same widget into one shared component, without changing a single pixel. Evidence at every step.

1. Inventory by grep, not vibes

Duplication has grep-able signatures. Sweep for:

• Raw Button(action: (or onClick handlers) not on a shared style —

icon-only tap targets (back/close/add/toggle) are the usual gap: kits ship a CTA style but no icon-button, so every screen hand-rolls one.

• Hand-rolled card/panel backgrounds (RoundedRectangle(cornerRadius,

bespoke border/shadow stacks) outside the shared card.

• Bare pill/chip shapes (Capsule(), rounded-full) outside the chip style.
• Ad hoc progress/ring/timer UI; empty-state blocks; badge overlays;

list rows; sheet headers; avatars. Output: every cluster with file:line pairs and a count. If the repo has a code graph (code-review-graph MCP), use similarity/dead-code detection to augment the grep pass.

2. Spec ~10-15 components with API sketches + dedup counts

For each: name, one-line API sketch, the call sites it collapses, estimated dedup count, and any special-axis readiness (e.g. which ones may adopt a material/glass treatment later). Rank by dedup impact; extract the top ones first. Keep a leave-list (genuinely bespoke shapes stay bespoke).

3. STALENESS WARNING: verify against current code before migrating

A spec inventory goes stale, and a component spec'd from one inventory pass with a single fixed rendering per style undershoots real variance. Lesson learned: a wave scoped to migrate ~50 inventoried legacy sites found ZERO were a pixel-exact match for the component's fixed recipe — different fills, strokes, tints, icon ratios, composite labels. Before any migration wave, re-audit each target site against the component's CURRENT rendering.

4. Variant axes from real call sites, never speculation

• Add bounded parameters (tint / background: chrome|solid|stroke|none /

size) only when real call sites demand them — driven by forward-looking needs of surviving screens, not back-fitted to legacy.

• Rule of two, strictly: no abstraction with fewer than two real users.
• Never fork a local copy of a component to get a variant; extend the

shared one with a bounded axis.

5. Don't migrate purge-listed code

Check the roadmap for views scheduled for deletion/replacement before migrating them. Migrating call sites in code that a pending flag-flip will delete is negative-value work. Purge-list status alone disqualifies a migration target regardless of component flexibility.

6. Extraction waves with the INVISIBLE-REFACTOR bar

• One PR per cluster family (cards, then icon buttons, then chips...).
• Each PR: move winning implementation to the shared kit, point users at

it, delete the twins, grep-proof the twin symbols are gone.

• Evidence bar: BEFORE/AFTER screenshots pixel-diffed to prove ZERO visual

change. This is a predicate, not a promise — and it catches real bugs (e.g. Swift silently binding a trailing closure to the wrong optional closure param; the pixel diff exposed it). Label optional-closure args explicitly at call sites.

• No behavior changes hidden inside consolidation PRs.

7. During parallel waves: prevent, ledger, consolidate after

When multiple agents build screens concurrently, don't block scene PRs on perfect sharing (each extraction is a cross-lane coordination event):

• Enforce cheap decision-level DRY now: tokens only, one data layer,

registries — mechanical CI gates.

• Second-use rule: the second lane needing a widget does NOT copy it —

owners agree the shared API and land a small extraction PR first.

• Duplication ledger: the merge gate records every tolerated near-duplicate

(what/where/twin/reason). The ledger is the consolidation work-list — nothing rides on memory.

• Consolidate once, after the wave, when true shapes are known: wrong early

abstractions are their own WET.

8. Ratchet

Add a duplicate-cluster-count baseline to CI: the count may only go down; a new cluster is red. Record the extraction map in project lore so future lanes know what exists in the kit before building.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.