/adoption-report

name: adoption-report
description: "Adoption report: coverage (what the system provides), reach (teams with access) and adoption (teams shipping with it), design vs engineering, trend and at-risk teams. Triggers: adoption report, usage metrics, which teams use the system. Not docs coverage — use docs-coverage."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(grep:*), Bash(rg:*), Bash(git log:*), Bash(npm view:*)
references:
  - ../../knowledge-notes/output-discipline.md
  - ../../knowledge-notes/adoption-measurement.md

Adoption report

A skill for producing a design system adoption report that separates coverage (how much of teams' needs the system provides), reach (which teams have access) and adoption (which teams actually ship with it), with trend direction and risk flags for teams where adoption is low or declining.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Coverage, reach and adoption are three different things, and treating them as one is among the most common ways design system reports mislead:

• **Coverage** is supply: how much of the teams' interface needs the system provides.
• **Reach** is access: which teams have the system available to them (package installed, Figma library enabled, onboarded).
• **Adoption** is use: which teams actually ship product work with it.

A system can reach all twenty product teams while only eight of them ship with it. Both facts are true; only one tells you how the system is performing. And if the system provides only a fraction of what those eight teams need, the constraint is coverage, not adoption. Low coverage is a supply problem the system team fixes by building; low adoption with good coverage is a demand problem the system team fixes by understanding why teams aren't consuming what exists (see the adoption-measurement note).

One caution on the word: Figma's library analytics and tools such as Omlet use "coverage" for the share of instances on a screen that come from the system. This pack uses it for supply. State the definition at the top of every report so a reader who knows the other usage isn't misled.

This skill holds the three measures separately 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

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `system.component_count` — informs small-system behaviour
• `integrations.*` — adoption data sources (see below)
• `recurring.*` — period-over-period comparison (see below)

**Maturity stage:** if a system-health report exists, take the maturity stage from it and cite it. Otherwise ask the user. Don't infer a stage from adoption data alone.

Auto-pull integrations

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

• Pull weekly/monthly download statistics for `integrations.npm.package_name` over the reporting period. On a private registry (`integrations.npm.registry_url`) download stats are usually unavailable; say so and skip
• Calculate trend direction from download data: increasing, flat, or declining
• For monorepos: pull per-package downloads from `integrations.npm.scoped_packages` — directional signals only (see monorepo caveat in component-audit)
• Compare current period downloads against previous period for the engineering adoption trend. Downloads show direction, never a count of adopting teams (see the note's npm caution)

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

• Library analytics (files using the library, insertion counts, detach rates per component) come only from the REST Library Analytics API on an Enterprise plan. If the team has it, pull them; if not, say design adoption wasn't measured and ask the design lead which teams' files use the library
• 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
• The API doesn't attribute usage to teams; team attribution comes from file ownership the user supplies

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

• Find which repositories import the design system packages — these are the actively adopting engineering teams (see the note's GitHub caution before counting)
• 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.

Recurring workflow

Follows the recurring-run pro