Adoption Report

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?

1. Add a "Period-over-period comparison" section to the report header showing the deltas
2. Flag persistent blockers — any blocker category present in 3+ consecutive reports is a systemic issue, not a one-time finding
3. 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
• 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 data is limited: the adoption report can be conducted as a structured assessment based on available signals rather than hard metrics. Note clearly in the output where figures are estimated rather than measured.

Step 1b: Adoption measurement calibration

Before calculating any metrics, calibrate the measurement against the system's maturity level and the current reporting period. Raw adoption percentages are misleading without context.

Maturity-appropriate adoption expectations:

| Maturity level | Expected adoption range | Interpretation guide | |---|---|---| | Level 1 (Ad-hoc) | 0–20% | Any adoption is a positive signal. Focus on whether early adopters are satisfied and whether the system is removing friction for them. Growth potential is high. | | Level 2 (Managed) | 20–50% | Growth is the key metric. Is adoption increasing quarter-over-quarter? This is the growth phase — adoption should be clearly trending up. | | Level 3 (Systematic) | 50–75% | Breadth matters. Are most teams using the system for most patterns? This is the critical transition phase — crossing 50% indicates the system is now central infrastructure. | | Level 4 (Measured) | 75–90% | Depth matters. Are teams using the system deeply, not just superficially? At this level, drops in adoption are concerning. Focus on why teams are not using the system for the remaining 10–25% of patterns. | | Level 5 (Optimised) | 85%+ | Maintenance matters. Is adoption holding steady without active promotion? At this level, the system should sustain adoption with minimal ongoing messaging. Declines are the primary concern. |

Calibration note for adoption interpretation: When writing the adoption picture synthesis in Step 5, frame the adoption percentage against the expected range for the system's maturity level. A Level 2 system at 35% adoption is healthy and growing — the focus is on acceleration. A Level 4 system at 35% adoption has a structural problem — focus is on diagnostic. The same percentage means very different things depending on context.

---

Step 2: Separate coverage from adoption

Before calculating any metrics, define what "coverage" and "adoption" mean for this reporting period.

Coverage definition

Coverage = teams that have access to the system and can use it, whether they are using it or not.

Signals that indicate coverage:

• 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

Coverage is the easy metric. A system available to twenty product teams has 100% coverage if all twenty have access. The challenge is actual usage.

Adoption definition

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

Before calculating any adoption metrics, align on what "adoption" means for this context. Different definitions produce different numbers — and comparing reports that use different definitions creates misleading trends.

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: ___

1. 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: ___

1. What counts as "engineering adoption"?

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

1. 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: Identify adopting teams and assess adoption depth

Gather team-by-team adoption data

For each team in scope, determine:

1. Design adoption status — Active / Partial / Not adopting
2. Engineering adoption status — Active / Partial / Not adopting
3. Usage indicators — specific components used, frequency, recency
4. 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)

Assessment categories

For each team, assign a status:

• Actively adopting: Team is shipping products with system components regularly. Usage is recent (within the last 30 days). Both design and engineering are engaged or one is engaged and the other is appropriately delegated.

• Partially adopting: Team has shipped with system components, but adoption is inconsistent. May be using the system for some patterns but building locally for others. Engagement is intermittent.

• Not adopting: Team has access but is not actively using the system in shipped work. Usage may have been exploratory or one-time.

• No engagement: Team has no known contact with the system. May not be aware it exists.

Document the assessment criteria you use so that this assessment can be repeated in future reporting periods.

---

Step 4: Identify at-risk teams and analyse blockers

At-risk team signals

Flag teams where adoption is declining, where there has been no engagement for an extended period, or where known blockers exist.

For each at-risk team, identify:

1. The signal — declining usage over time, no recent engagement (6+ weeks without contact), known issue report, or team communication indicating plans to move away from the system
2. The likely cause if known — from blocker analysis, support conversations, or team feedback
3. Recommended next step — reach out to discuss the blockers, offer support, gather more information, or schedule a working session

At-risk teams are the most actionable section of the report. Adoption work is most effective early — a team that has disengaged for six months is significantly harder to re-engage than a team that has been quiet for six weeks.

Adoption blockers analysis

Based on what is known from team interactions, support requests, and survey data: what are the most commonly cited reasons for non-adoption or partial adoption?

Group blockers into categories:

• Missing components or patterns: the system does not have what teams need
• Documentation gaps: teams cannot find how to use what exists
• Integration friction: technical barriers to consuming the system (installation, build integration, framework compatibility)
• Awareness gaps: teams do not know the system exists or have not discovered what they need
• Tooling misalignment: the system is built for a different tech stack or tooling context than some teams use
• Governance or process friction: the contribution process is unclear, or the system feels gatekept rather than collaborative
• Reliability concerns: the system has had breaking changes without migration paths, causing teams to maintain local copies for stability

For each category: how many teams or incidents cite this as a blocker, and what would address it.

Flag if one blocker category dominates. If "missing components" is cited by 80% of at-risk teams, that is a different problem than if "awareness gaps" dominates. The remediation is category-specific.

---

Step 5: Produce the report

---

Design system adoption report

Period: [reporting period] Date: [date] Previous report: [link or date, if applicable] Adoption definition: [the agreed definition from Step 2] Maturity level: [current system maturity — Level 1/2/3/4/5]

---

Period-over-period comparison (if recurring)

| Metric | This period | Previous period | Change | Trend | |---|---|---|---|---| | Teams in scope | [n] | [n] | [+/-] | | | Coverage | [%] | [%] | [+/-] | | | Active adoption | [%] | [%] | [+/-] | | | Design adoption | [%] | [%] | [+/-] | | | Engineering adoption | [%] | [%] | [+/-] | | | At-risk teams | [n] | [n] | [+/-] | |

---

Coverage vs adoption summary

| | Design | Engineering | Combined | |---|---|---|---| | Teams in scope | [n] | [n] | [n] | | Teams with access (coverage) | [n] ([%]) | [n] ([%]) | [n] ([%]) | | Teams actively adopting | [n] ([%]) | [n] ([%]) | [n] ([%]) | | Change from last period | [+/- n] | [+/- n] | [+/- n] |

---

Adoption picture

One paragraph synthesising the adoption state. Include:

• Overall direction

…

Source & license

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

• Author: murphytrueman
• Source: murphytrueman/design-system-ops
• License: MIT
• Homepage: https://www.designsystemops.com

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