/adoption-report

name: adoption-report
description: "Produce a design system adoption report separating coverage from actual adoption, with trend direction and risk flags. Trigger when someone says: adoption report, how much is the system being used, usage metrics, adoption status, coverage report, which teams are using the system, who's not using the system, or anything about measuring or reporting on how widely the design system is being used. Here 'coverage' means adoption coverage (how much of the system teams actually use). Do NOT trigger for documentation coverage or doc staleness — use docs-coverage for whether the documentation surface keeps pace with the components."
references:
  - ../../knowledge-notes/output-discipline.md
  - ../../knowledge-notes/adoption-measurement.md

Adoption report

A skill for producing a design system adoption report that distinguishes coverage (who has access and can use the system) from adoption (who is actively using it), with trend direction and risk flags for teams where adoption is low or declining.

Context

Coverage and adoption are not the same thing, and treating them as equivalent is one of the most common ways design system reports mislead. A system available to twenty product teams has 100% coverage. If only eight of those teams are actively using it, adoption is 40%. Both numbers are true. Only one of them tells you how the system is actually performing.

This skill produces a report that holds both numbers separately and distinguishes between them throughout. It also separates adoption across two dimensions that are frequently conflated: design adoption (are designers using the Figma library?) and engineering adoption (is the code being consumed from the system?). High design adoption with low engineering adoption is a specific kind of problem — the design side is working but the handoff is broken. The reverse is also a specific kind of problem.

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `system.component_count` — informs small-system behaviour
• `system.maturity_level` — informs adoption expectations calibration (see Step 1b)
• `integrations.*` — enables auto-pull for adoption data (see below)
• `recurring.*` — enables trend comparison against previous reports

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically:

**npm registry** (`integrations.npm.enabled: true`):

• Pull weekly/monthly download statistics for `integrations.npm.package_name` over the reporting period
• Calculate trend direction from download data: increasing, flat, or declining
• For monorepos: pull per-package downloads from `integrations.npm.scoped_packages` — note these are directional signals (see monorepo caveat in component-audit)
• Compare current period downloads against previous period for the engineering adoption trend

**Figma MCP** (`integrations.figma.enabled: true`):

• Pull library analytics from `integrations.figma.file_key` if available via the Figma REST API
• Extract: number of files using the library, component insertion counts, detach rates
• Detach rates are a design adoption quality signal — high detach rates mean designers are pulling components but modifying them, which is partial adoption at best
• Use library file count as the numerator for design adoption percentage
• Track which teams are using the library by analysing team membership in Figma workspace analytics if available

**GitHub** (`integrations.github.enabled: true`):

• Count import references for design system packages across consuming repositories using `gh api search/code`
• Track which repositories import the system — these are the actively adopting engineering teams
• Pull contribution activity: PRs from consuming teams into the design system repo indicate healthy engagement
• Note recency: repositories with no imports in the last 6 months may indicate disengagement or migration to a competitor solution

**Documentation platform** (`integrations.documentation.enabled: true`):

• If the documentation platform has analytics (Zeroheight, Supernova): pull page views per component doc
• High-view-count pages indicate actively used components; zero-view pages indicate unused or undiscoverable documentation
• Track search logs if available — what terms are teams searching for that return no results? These are adoption blockers.

If an integration fails, log it and proceed with manual data gathering. Do not block the adoption report on integration availability.

Recurring workflow

If `recurring` is configured in `.ds-ops-config.yml`:

1. **Load the previous adoption report** from `recurring.output_directory`. 2. **Auto-populate the trend direction** by comparing current period data against the previous report:

• Coverage change: +/- teams
• Adoption change: +/- teams (design and engineering separately)
• At-risk teams: newly at-risk vs. previously at-risk now recovered
• Blocker categories: which blockers are persistent vs. newly resolved?

3. **Add a "Period-over-period comparison" section** to the report header showing the deltas 4. **Flag persistent blockers** — any blocker category present in 3+ consecutive reports is a systemic issue, not a one-time finding 5. **Save output** and prune per `recurring.retain_count`.

---

Step 1: Gather adoption signals

Ask for or confirm (skip questions already answered by auto-pull):

• Which teams or products are in scope?
• What data is available? (Figma library analytics, npm download stats, component usage in codebases, survey data, self-reported figures)
• What is the reporting period? (Quarter, year, or since last report)
• Is there a previous adoption report to compare against for trend direction?

Step 1a: Adoption signal inventory

Before proceeding, audit which adoption signals are available and their reliability:

**Direct signals (measured data):**

• npm download statistics
• Fig