Adoption Report

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 procedure in the configuration-and-recurring note. Specific to this skill:

• "Period-over-period comparison" section showing the deltas against the previous report, which also sets the trend direction:
  • Coverage change: needs served vs. unserved
  • Reach 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?
• Flag persistent blockers — any blocker category present in 3+ consecutive reports is a systemic issue, not a one-time finding

---

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?
• Who is the audience? The system team gets the team-level report; leadership gets system-level aggregates (see Step 5).

Step 1a: Adoption signal inventory

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

Direct signals (measured data):

• npm download statistics (direction only — see the caveat above)
• Figma library analytics (files using library, insertion counts, detach rates)
• Code import counts per repository
• Documentation platform analytics (page views per component)
• Support ticket volume by team or component

Indirect signals (structural inference):

• Components added to repositories in recent commits (evidence of recent adoption)
• Component usage in shipped products vs. experimental branches
• Design file inventory (how many files reference the design system library)
• Pull request activity between consuming teams and the system repository
• Team interviews or surveys

Document which signals are available and which are unavailable. Adoption assessment is only as strong as the signals used — if only one signal is available, note that the adoption assessment is based on limited data and may be incomplete.

If no team has a measured signal, stop. Don't fill a team-by-team table with estimates. Output a data-collection plan instead: for each team, which signal to collect (the code recipe below, library analytics, a five-question survey), how, and who. Label every figure that does appear measured (with its source), or reported by the team; there is no "estimated" row in an adoption table.

Step 1c: Measure engineering adoption from code

The one signal almost every team can measure. For each consuming repository in reach:

1. Reach: the system package is a dependency (package.json) and is imported somewhere: rg -l "from '@org/ds" --glob '*.{ts,tsx,js,jsx,vue}'.
2. Adoption depth: count system component instances against local look-alikes. If the consumer has a .ai/index/ from codebase-index, read the usedBy edges and the inventory of local components; otherwise count <Name[\s/>] for each system component and for each local component that duplicates one (LocalButton, a Button under src/components/ in the consumer). Report "system instances of [total instances of that role]" per component role. react-scanner and Omlet produce this share for React codebases; if either is set up, take its numbers and cite the report.
3. Token adoption: the share of token references against raw values in the consumer's styles, from token-compliance's positive-controlled search.
4. Positive control: before reporting any team as "None", confirm the import pattern finds a component you know they use. If it can't, the pattern doesn't fit that repo, and the cell is "not measured", not "None".

Step 1b: Frame adoption against the maturity stage

Raw adoption figures are misleading without context, and there is no sourced benchmark for what adoption "should" be at each stage. Frame the figures qualitatively against the named stage (from system-health or the user):

• Ad-hoc or Managed: direction matters most. Is adoption growing period on period, and are early adopters getting what they need?
• Systematic: breadth matters. Are most teams using the system for most of the patterns it covers?
• Measured: depth matters. Are teams using the system deeply, not superficially, and are declines being caught early?
• Optimised: stability matters. Is adoption holding without active promotion? Declines are the primary concern.

The same figure means different things at different stages: a Managed system with a third of teams adopting and growing is on track; a Measured system at the same figure has a structural problem worth diagnosing.

---

Step 2: Separate coverage, reach and adoption

Before calculating any metrics, define each measure for this reporting period.

Coverage (supply)

Coverage = how much of the teams' interface needs the system provides.

Signals: an inventory of the patterns teams build against what the system offers; local components that fill needs the system doesn't cover; missing-component requests. A team building a local date picker because the system has none is a coverage gap, not an adoption failure.

Reach (access)

Reach = teams that have the system available to them, whether they use it or not.

Signals:

• Team has the npm package installed in their production codebase
• Team has the Figma library enabled in their workspace
• Team has been formally onboarded or given access
• Team has documentation and knows the system exists

Reach is the easy measure. The challenge is actual use.

Adoption (use)

Adoption = teams actively consuming design system components in shipped product work, not just installed or in explorations.

Different definitions produce different numbers, and comparing reports that use different definitions creates misleading trends. Align on the definition first.

Adoption definition worksheet:

1. What counts as "using the system"?

   • Installed the package (weakest signal — installed is not adopted)
   • Imported at least one component in production code
   • Using 3+ components in production
   • Using the system for 50%+ of interface patterns
   • Other: ___

2. What counts as "design adoption"?

   • Figma library is enabled
   • Components from the library appear in current design files
   • Designers are using library components without detaching
   • Other: ___

3. What counts as "engineering adoption"?

   • Package is installed
   • Components are imported in production code
   • Token references are used (not hardcoded values)
   • Other: ___

4. What is the threshold for "partial" vs "full" adoption?

   • Partial: ___
   • Full: ___

Document the chosen definitions at the top of the report. Use the same definitions for every subsequent report to enable meaningful trend comparison.

Why separate design from engineering adoption

Design adoption and engineering adoption are independent. Common patterns:

• High design adoption, low engineering adoption: Design system is working, but engineering handoff is broken. The components are being designed with the system, but engineers are not implementing them from the code library. Investigate: are the code components available? Are they what designers think they are? Is there a documentation or discovery gap?

• Low design adoption, high engineering adoption: Engineers are adopting the system's code, but designers are not using the Figma library. Investigate: is the design library up to date? Is it discoverable? Are there design tokens being used that are not reflected in the code?

• Both low: System has not crossed the adoption threshold. The focus is on why — is there a blocker that explains both, or are design and engineering facing different problems?

---

Step 3: Assess each team

For each team in scope, determine:

1. Adoption stage — from the adoption-measurement note: Aware / Installed / Consuming / Contributing / Advocating, or Not reached if the team has no access or doesn't know the system exists
2. Design adoption — Active / Partial / None
3. Engineering adoption — Active / Partial / None
4. Usage indicators — specific components used, frequency, recency
5. Engagement signals — questions asked, contributions made, documentation viewed

Sources for per-team data:

• Code import analysis (which repos import the system)
• Figma team access logs and component usage
• Support tickets and questions attributed to teams
• Direct interviews or surveys with team leads
• Git commit history (who is merging PRs that add system components)

Each stage carries its intervention from the note: Aware needs onboarding support, not pressure; Installed needs its barriers identified; Consuming needs support and its gaps addressed; Contributing needs a streamlined contribution path; Advocating teams can be enabled to support peers.

For teams with partial adoption, note which areas of the system they use and which they build locally, and whether the local work is a coverage gap (the system doesn't provide it) or a choice (it does). Document the criteria you used so the assessment can be repeated next period.

---