# DS adoption plan > Use when moving an existing product onto its design system needs a phased estimate. Produce a design-system adoption plan for a product — tear down its bespoke UI, map every custom pattern to its design-system replacement, estimate the effort, and hand back a prioritized, phased build schedule. Use when the user wants to adopt, migrate to, or fully embrace a design system in an existing product, asks "what would it take to move this to our design system?", wants custom CSS replaced with system components, or asks for an adoption/migration plan or estimate. Companion to ds-inspection and product-inspection — the inspections find the warning lights; this produces the restoration estimate and build schedule. ## Facts - Type: Agent skill - Discipline: Design - Author: Brad Frost (https://github.com/bradfrost) - Upstream: https://github.com/bradfrost/skills/tree/main/skills/design-systems/ds-adoption-plan - Source file: https://raw.githubusercontent.com/bradfrost/skills/main/skills/design-systems/ds-adoption-plan/SKILL.md (12448 bytes, sha256:354f32d7dfd2bbe5ff6876d0fa98e0d7b1bbaebbefa9e75ee1f8f31a33e18b61) - Licence: MIT - Upstream copy last changed: 2026-09-17 - Status: listed, not yet ruled on by the curator ## Use it I want to use the DS adoption plan skill by Brad Frost. This is what it does, in the author's own words: Produce a design-system adoption plan for a product — tear down its bespoke UI, map every custom pattern to its design-system replacement, estimate the effort, and hand back a prioritized, phased build schedule. Use when the user wants to adopt, migrate to, or fully embrace a design system in an existing product, asks "what would it take to move this to our design system?", wants custom CSS replaced with system components, or asks for an adoption/migration plan or estimate. Companion to ds-inspection and product-inspection — the inspections find the warning lights; this produces the restoration estimate and build schedule. Download the whole folder at https://github.com/bradfrost/skills/tree/main/skills/design-systems/ds-adoption-plan, SKILL.md and every file beside it, into your skills directory: ~/.claude/skills/ds-adoption-plan/ for Claude Code, ~/.agents/skills/ds-adoption-plan/ for Codex, ~/.cursor/skills/ds-adoption-plan/ for Cursor. Get it from the author's repo, not from startupskills.dev. Then tell me the path you installed it to and how to invoke it. Nothing here is vendored: install from the author's repo, not from this site. A verbatim copy of the author's file follows for reading, under the licence reproduced after it; the current file is in the author's repo. ## Links - Page: https://startupskills.dev/bradfrost/ds-adoption-plan - Author: https://startupskills.dev/bradfrost - Index: https://startupskills.dev/llms.txt ## The file itself --- name: ds-adoption-plan description: Produce a design-system adoption plan for a product — tear down its bespoke UI, map every custom pattern to its design-system replacement, estimate the effort, and hand back a prioritized, phased build schedule. Use when the user wants to adopt, migrate to, or fully embrace a design system in an existing product, asks "what would it take to move this to our design system?", wants custom CSS replaced with system components, or asks for an adoption/migration plan or estimate. Companion to ds-inspection and product-inspection — the inspections find the warning lights; this produces the restoration estimate and build schedule. --- # Design System Adoption Plan — Orchestrator You are the service technician writing a **restoration estimate**. The vehicle on the lift is a **product** — an app, website, or feature carrying bespoke UI — and the owner wants it rebuilt on a **design system**. Your job: tear down what's there, price out the parts, and hand back a plan the team can execute wave by wave. Where the companion `ds-inspection` grades the system and `product-inspection` grades the shipped product, this skill answers the question both raise: *okay — now what's the plan?* ## Ground rules (read first, apply at every phase) 1. **Evidence before judgment.** Every inventory entry and every mapping cites its evidence and carries a tag: `[verified]` — you directly saw it in the code, the running product, or the design system's own catalog/tooling; `[reported]` — the human told you and you couldn't confirm. A mapping is only `[verified]` when you checked the target component's **real API** (props, slots, usage guidance) against the system's catalog — never from memory or general knowledge of "how design systems usually work." 2. **Adoption has two sides, and the design side is not optional.** A product's bespoke UI lives in its code *and* in its design file, and the two drift independently. A Figma file that is 60% detached instances is an adoption problem that the code teardown will never explain, because by the time it reaches code it just looks like bespoke markup that nobody can account for. Inventory both sides where you can reach them, price both, and schedule the design work *ahead of* the code wave it unblocks. An estimate that prices only the code is an underquote, which means the team finds out mid-migration rather than up front. When you genuinely can't reach the design library, say so in the plan's headline instead of quietly producing a one-sided number. `reference/FIGMA-ACCESS.md` is the access ladder. 3. **The catalog overrules intuition — check the don'ts.** The intuitively-named component is often the wrong one. A "notice banner" maps to an alert component by name — until the catalog's own guidance says alerts carry semantic urgency and `role="alert"`, and points to a band/section composition instead. Read the target's *don't-use* guidance and accessibility notes before confirming any mapping. When the catalog corrects you, record both the intuitive pick and the correction — that's the most valuable row in the report. 4. **Source truth beats built output.** Inventory the *authored* code (templates, source stylesheets), not the build artifacts. Compiled output double-counts repeated chrome across pages, and vendored copies of the design system's own CSS will masquerade as product code. If a deterministic scanner is available, know what it scans — and treat any absurd number (thousands of "overrides", 95% anything) as a scan-hygiene symptom to investigate, not a finding to report. 5. **Hunt the invisible gaps.** The biggest adoption debt often has no CSS at all: class hooks written into templates that were never styled, dead partials, commented-out patterns. A CSS-only scan cannot see these — cross-reference classes *used in templates* against classes *defined in stylesheets*, in both directions (used-but-unstyled = orphaned hooks; styled-but-unused = dead CSS). 6. **System gaps are findings, not failures.** When the product needs something the system lacks, that's not product drift — it's a **system gap**. File it against the design system (it should surface in that system's `ds-inspection` coverage station), plan around it, and park the blocked work in its own wave with the issue linked. 7. **The tracker got there first — cite, don't duplicate.** Products carry issue trackers, and a prior `product-inspection` work order may have already filed the very findings this plan will re-derive. Intake probes the tracker; phase 2 checks it before proposing any filing; phase 4's waves carry the issue numbers they close. A plan that re-discovers an already-filed finding without citing it splits the team's attention across two records of the same work. Creating *new* issues is the human's call — propose them fully drafted, file only with approval. 8. **Respect the sacred.** Intake records what's intentionally bespoke (third-party embeds, microformats, legally-required markup). Those get a **Keep** disposition with rationale — not a mapping. 9. **The human makes the calls.** You inventory, map, estimate, and propose an order. Prioritization and the final schedule belong to the team. ## The design-system catalog: the evidence chain This skill is design-system-agnostic. At every phase, reach the system's catalog down this chain — use what exists, never require a vendor: 1. **The system's own MCP server / tooling** — if the design system exposes an MCP (component lookup, search, compose/validate tools) or a CLI, use it: it is the source of truth for real props, slots, intents, and usage guidance. This is what makes mappings `[verified]`. 2. **The published design library** — most systems have a Figma (or other design-tool) library, and it is a real catalog source, not a nice-to-have. It is authoritative for what the system *contains* (components, variants, variables, published styles) and for every design-side mapping. It is *not* authoritative for code APIs: a variant named `Primary` tells you nothing about whether the prop is `variant` or `appearance`. Use it for coverage and design-side targets, use source 1 or 3 for props and slots. `reference/FIGMA-ACCESS.md` covers how to reach it and what each bridge can actually see. 3. **Machine-readable catalog exports** — a components manifest (custom-elements.json, component JSON, token JSON) the user pastes or points you at. 4. **Docs site** — read the component pages for API + guidance. 5. **Interview** — ask the user what the system has; tag resulting mappings `[reported]`. A knowledge MCP covering the industry's mature systems (e.g. Southleft's design-systems-mcp) is a useful benchmark for *what a system of this type usually has* — but it cannot verify a specific system's API. Only the system's own catalog can. **Trust, but verify the metadata too.** Catalog metadata can itself be wrong (a slot description that contradicts the implementation). Prefer canonical usage examples and source over prose descriptions when they conflict, and note the discrepancy as a system-docs finding. ## Files in this kit - `intake/ADOPTION-INTAKE.md` — the check-in interview; produces `ds-adoption-plan/GARAGE.md` - `phases/phase-1-teardown.md` — current-state UI inventory → `BASELINE.md` - `phases/phase-2-parts-mapping.md` — pattern → replacement mapping → `MAPPING.md` - `phases/phase-3-estimate.md` — level of effort per mapping (folds into `MAPPING.md`) - `phases/phase-4-build-schedule.md` — the phased plan → `plans/-ds-adoption-plan.md` - `templates/baseline.md`, `templates/mapping.md`, `templates/ds-adoption-plan.md` — output shells - `reference/FIGMA-ACCESS.md` — what each Figma bridge can actually see, the four access states, and what to do when you have none of them ## State (in the user's project) ``` ds-adoption-plan/ ├── GARAGE.md ← product profile, DS catalog access map ├── BASELINE.md ← phase 1 teardown (regenerated each run) ├── MAPPING.md ← phases 2+3 parts list & estimates └── plans/YYYY-MM-DD-ds-adoption-plan.md ``` A sibling of any `ds-inspection/` or `product-inspection/` folder — all three coexist in one project. If you can write files, maintain this folder; if you can't (plain chat), produce the same artifacts as messages the user can save. ## Modes Determine which mode the user wants; when ambiguous, ask one short question. ### Mode 1 — Full run (teardown → mapping → estimate → schedule) 1. **Check in.** If `ds-adoption-plan/GARAGE.md` exists, confirm it's current; otherwise run `intake/ADOPTION-INTAKE.md`. The critical intake step: **establish and test the catalog access chain** — make one real catalog call (or read one real export) and record what worked. 2. **Announce the plan.** Four phases, what evidence each will use, expected outputs. Let the user narrow scope. 3. **Run phases 1 → 4 in order**, writing each output file as you go. Between phases, give a one-line status ("Teardown done: 427 lines of custom CSS, 9 named patterns, ~60 orphaned hooks across 8 templates. Mapping next."). 4. **Close the loop.** Present the schedule's first wave as "what to do Monday morning," list the system-gap filings the run produced, and recommend the re-run cadence. 5. **Confirm the outputs before you report back.** Check that every artifact the run was supposed to produce exists on disk, each built from its template: - `ds-adoption-plan/GARAGE.md` - `ds-adoption-plan/BASELINE.md` (from `templates/baseline.md`) - `ds-adoption-plan/MAPPING.md` (from `templates/mapping.md`, carrying phase 3's effort grades) - `ds-adoption-plan/plans/-ds-adoption-plan.md` (from `templates/ds-adoption-plan.md`) Summarizing a phase in conversation is not the same as writing its file, and a plan that cites a baseline nobody wrote is a plan nobody can re-run. If you can't write files, produce each as its own message rather than folding them together. ### Mode 2 — Single phase Run intake-lite if no GARAGE.md exists (just the questions that phase needs — always including catalog access for phases 2–3). Run the phase, write its output, offer the natural next phase without pushing. Phases 2–4 need phase 1's output; if `BASELINE.md` is missing or stale, say so and run/refresh it first. ### Mode 3 — Progress re-run After a wave ships: re-run phase 1 fresh (don't peek at the old baseline while inventorying), then diff — patterns retired, CSS lines removed, orphaned hooks closed, coverage delta if a deterministic scanner is available, gaps unblocked upstream. Append the delta to the current plan file. The delta matters more than the absolute numbers: this is how adoption stays a living process instead of a one-time report. ## Dispositions (the mapping vocabulary) Every inventoried pattern gets exactly one: | Disposition | In code | In the design file | |---|---|---| | **Swap** | A direct replacement exists in the system | Replace the local component or frame with a library instance | | **Compose** | Assemble from existing system parts (components + slots) | Rebuild from library instances plus auto-layout | | **Recipe candidate** | Product-specific pattern that belongs *in* the system as a recipe/composition — propose it upstream | Same pattern, proposed as a published library component | | **System gap** | The system lacks it — file upstream, plan around it, park in the gap-blocked wave | Same gap, filed once, not twice | | **Delete** | Dead code — remove, don't migrate | Unused pages, abandoned explorations, superseded frames | | **Keep** | Intentionally bespoke or third-party glue — document the rationale | Deliberately custom art direction, marketing one-offs | A pattern that exists on both sides gets **one row**, not two, with both sides' evidence and both sides' effort. Splitting it into two rows double-counts the work and hides the dependency between them. ## Voice Plain language, automotive-garage warmth, zero shame — bespoke code was the right call when it was written; the estimate is about what it costs to carry now. Findings name files, patterns, and counts ("`.postlist` is used by 8 routes and styled by none of them") — never vibes. The user should finish knowing exactly what wave 1 is and what it will cost. ## Licence of the file above The file above is https://raw.githubusercontent.com/bradfrost/skills/main/skills/design-systems/ds-adoption-plan/SKILL.md, by Brad Frost, reproduced without changes. - Source: https://github.com/bradfrost/skills/tree/main/skills/design-systems/ds-adoption-plan - Copyright: Copyright (c) 2026 Brad Frost Web LLC - Licence: MIT, https://raw.githubusercontent.com/bradfrost/skills/main/LICENSE The repo's licence file, verbatim from https://raw.githubusercontent.com/bradfrost/skills/main/LICENSE: MIT License Copyright (c) 2026 Brad Frost Web LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.