Design system component inventory template: map design, code, usage, and decisions

An undated spreadsheet called "all components" becomes unreliable almost immediately. Before listing anything, state what the inventory covers and what it deliberately excludes. Every later conclusion can then be checked. This boundary also stops a team from treating a partial Figma scan or package export as a complete view of the estate.

• Inventory date and reviewer: when the snapshot was taken and who assembled it.
• System boundary: the design system name, version, release, or branch under review.
• Products and platforms: the named web applications, mobile applications, services, or embedded surfaces included.
• Design sources: the exact libraries, files, pages, branches, and versions inspected.
• Code sources: the packages, repositories, registries, versions, and relevant directories inspected.
• Documentation sources: the catalog, Storybook, reference site, decision records, or migration guidance inspected.
• Owners: the people or teams responsible for source decisions, implementation, documentation, and product exceptions.
• Exclusions: products, repositories, archived files, experiments, or protected consumers intentionally left outside the audit.
• Sampling rule: how consumers were selected and what the sample cannot prove.

Use a table, database, or structured document that your team can version and review. Keep the fields below even when a value is unresolved. An empty cell is ambiguous. An explicit status tells the next reviewer whether the field is required, conditional, unresolved, or not applicable.

inventory_id: cmp-0001
snapshot_date: YYYY-MM-DD
inventory_boundary: <system, version, products, platforms>

canonical_name: <governed component name>
aliases: []
component_kind: <component | pattern | template | primitive>
contract_summary: <purpose and supported behavior>

# Design identity
design_source: <library/file/page>
design_component_key: <stable ID or path>
design_version: <version, branch, or date>
design_variants: []
design_states: []

# Code identity
code_package: <package or repository>
code_export: <public export or path>
code_version: <resolved version or commit>
framework_or_platform: <React, Web Components, iOS, etc.>
dependencies: []

# Documentation
documentation_url_or_path: <reference>
documented_variants: []
documented_states: []
known_limitations: []

# Estate relationships
named_consumers: []
alias_of: null
wraps: null
forked_from: null
duplicate_candidates: []
local_exceptions: []

# Evidence
evidence_state: <declared | delivered | mapped | adopted | observed>
evidence_records: []
proof_limit: <what this evidence does not establish>

# Governance
source_owner: <team or person>
consumer_owner: <team or person>
lifecycle_status: <active | candidate | deprecated | local | unknown>
disposition: <keep | merge | replace | deprecate | approved_exception | unresolved>
decision_rationale: <why>
correction_owner: <team or person>
retest_trigger: <change or date>
next_review_date: YYYY-MM-DD

• Required: the row cannot support a decision until this value is known.
• Conditional: required only when the relationship or feature exists, such as a wrapper target.
• Unresolved: relevant, but the current audit has not established the answer.
• Not applicable: inspected and found outside the component's declared contract, with a short reason.

Don't use "N/A" for both unknown and irrelevant. They lead to different work. An unknown needs an owner or another inspection. Not applicable needs a reason that later reviewers can challenge if the boundary changes.

First ask whether two records describe the same contract. Names are only clues. A design component called "Primary button," a code export called Button, and documentation titled "Call to action" might describe one component, three variants, or unrelated controls. Compare their intended purpose, supported content, variants, states, behavior, accessibility responsibilities, and change authority.

Choose a canonical inventory identity only after this comparison. Preserve old names in aliases. Use wraps when a local component delegates to a governed one while adding a supported contract. Use forked_from when the implementation has diverged and no longer follows upstream changes. Keep possible duplicates in duplicate_candidates until you've compared their contracts and consumers.

A component can be documented, packaged, imported, used, and observed at different times. A single "done" checkbox collapses those facts and creates false confidence. Assign the strongest state the evidence supports, then retain the lower-level records that establish the chain.

Every observation should include the consumer, deployed or resolved version, environment, mode, state, content condition, viewport or platform when relevant, date, result, and evidence location. "Button works in checkout" is too broad. "Web checkout 4.18.2, production-like staging, light mode, disabled submit state, long German label, 390 px viewport, observed 2026-10-05" is specific enough to review and repeat.

Don't merge rows simply because two controls look alike. Normalize their relationship first. This is the point where the inventory becomes useful for migration planning instead of remaining another count of files.

• Alias: another name for the same governed contract. Preserve the name and point it to the canonical record.
• Duplicate candidate: two records appear to solve the same task, but their equivalence has not been established.
• Wrapper: a component delegates to another component and intentionally adds behavior, defaults, analytics, platform adaptation, or policy.
• Fork: a component originated from another implementation but now changes independently or cannot safely consume upstream releases.
• Local variant: a bounded extension within the canonical component's supported variation model.
• Approved local exception: a deliberate departure with a named consumer, rationale, owner, review date, and removal or renewal condition.
• Accidental divergence: a difference with no recorded authority or product requirement. Route it for correction instead of legitimizing it through the inventory.

One component may have several relationships. A checkout button can wrap the system button for analytics, retain an old alias in one product, and contain an unapproved spacing override. Record each fact separately. Calling the whole thing a "custom button" hides the legitimate wrapper and the correctable divergence.

An inventory should end in a decision or an explicitly unresolved question. Base that outcome on authority, functional divergence, change reach, adoption evidence, migration path, and ownership. Popularity alone doesn't make a component canonical. Likewise, the existence of a replacement doesn't make the old component safe to remove.

Don't begin by counting every icon and primitive. Start with a component family whose inconsistency can affect important tasks, many consumers, or costly states. Buttons, inputs, navigation, dialogs, tables, and status messaging often reveal more about the estate than a flat alphabetical sweep. Still, your priority should follow the products and risks inside the boundary.

1. 1

   Rank component families

   Score current reach, task importance, state complexity, accessibility responsibility, release frequency, duplicate signals, and migration pressure. Record the rationale instead of presenting the score as universal truth.

2. 2

   Select a defensible sample

   Choose named consumers that cover the highest-reach product, a materially different platform or framework, a known local exception, and a consumer likely to expose stale adoption. State which products remain uninspected.

3. 3

   Collect source identities independently

   Record design, code, documentation, and package identities before trying to reconcile them. This reduces the chance that one catalog's naming silently controls the audit.

4. 4

   Map relationships and evidence states

   Connect aliases, wrappers, forks, variants, and consumers. Assign the strongest evidence state that each claim actually supports.

5. 5

   Inspect representative conditions

   Check the modes, states, content conditions, environments, and platform differences required by the component contract. Record observations against named versions.

6. 6

   Choose a disposition

   Apply keep, merge, replace, deprecate, approved exception, or unresolved. Name the decision owner and the evidence that could change the decision.

7. 7

   Set the retest trigger

   Use a meaningful event such as a source contract change, package release, consumer migration, exception expiry, new platform adoption, or scheduled review date.

Make the completion claim match the procedure. If you audited the button family across four selected products, you completed a button-family sample across those four products. You did not complete a component inventory for the organization.

The following row is fictional. It shows how to keep known identities and pending evidence in the same record. It isn't evidence about Identity Forge, Carbon, VA, UMD, or any other real system.

inventory_id: cmp-0017
snapshot_date: 2026-10-05
inventory_boundary: Atlas Web System 3.4; account and checkout web apps
canonical_name: Button
aliases: [PrimaryButton, CTAButton]
component_kind: component
contract_summary: Triggers an immediate user action

design_source: Atlas UI / Controls library
design_component_key: controls/button
design_version: 3.4
design_variants: [primary, secondary, destructive]
design_states: [default, hover, focus, disabled, loading]

code_package: "@atlas/ui"
code_export: Button
code_version: 3.4.2
framework_or_platform: React
dependencies: [semantic color roles, focus-ring contract]

documentation_url_or_path: Storybook / Actions / Button
known_limitations: [icon-only use is outside this contract]

named_consumers:
  - account/settings-save
  - checkout/place-order
wraps: null
forked_from: null
duplicate_candidates: [CheckoutButton]
local_exceptions:
  - consumer: checkout/place-order
    status: unresolved
    note: CheckoutButton adds analytics and unknown visual overrides

evidence_state: mapped
evidence_records:
  - account imports Button from @atlas/ui 3.4.2
  - checkout imports local CheckoutButton wrapper
proof_limit: No rendered consumer state was observed during this inventory pass

source_owner: Design System Team
consumer_owner: Account and Checkout teams
lifecycle_status: active
disposition: unresolved
decision_rationale: Wrapper behavior and visual divergence have not been separated
correction_owner: Checkout team
retest_trigger: Inspect CheckoutButton default, focus, disabled, loading, and error-path use before deciding merge or approved exception
next_review_date: 2026-10-19

When design, documentation, code, and the product disagree, fix the first layer that diverges from its governing input. Fixing only the final screenshot can leave the cause intact and create another local exception.

1. Source decision: Is the intended component contract explicit, current, approved, and owned?
2. Delivered artifact: Does the expected design asset, package, or generated output contain that contract at the recorded version?
3. Project mapping: Does the consuming project resolve the intended package, export, token roles, and component version?
4. Component contract: Does the implementation support the required variants, states, content, and behavior?
5. Approved exception: Is any divergence deliberate, bounded, owned, and still within its review period?
6. Consumer use: Does the named product use the intended component or wrapper without an accidental local substitute?
7. Rendered observation: Under the recorded environment and condition, did the expected result occur?

Assign the correction owner at the first failed layer. Set a retest trigger that reaches the same consumer and condition. A stale package mapping belongs to the consuming project, while an omitted supported state may belong to the component implementation. A valid local exception needs review, not silent removal.

Choose one component family with meaningful reach. Complete its identities and relationships, inspect representative consumers, and make every row decision-ready. That first family will show which fields your organization can answer, where ownership is missing, and which evidence is expensive to obtain.

Don't expand the inventory merely to increase the row count. Expand once the first family has named owners, explicit proof limits, actionable dispositions, and retest triggers. The next step is concrete: freeze today's boundary and complete one real component row from source identity through a named consumer.

• Design System Component Creation Checklist Template - Notion: The captured page presents a checklist spanning component design, development, documentation, verification, and deployment.
• Design system checklist - Webflow University: Webflow's checklist covers system foundations, reusable styles and components, sharing, organization, and maintenance.
• Components | UMD Design System - University of Maryland: UMD publishes a categorized catalog that makes components and their intended purposes discoverable within its design system.
• Components - VA.gov Design System - Veterans Affairs: The VA catalog distinguishes components from patterns and templates and provides ecosystem-specific governance guidance.
• Component checklist - Carbon Design System: Carbon's definition of done separates design specification, code, testing, and design-kit requirements for component contributions.
• Creating a design system / component library as a solo dev in a small agency: The captured practitioner discussion shows demand for deciding what to address first and identifying the intended consumers of a component library.
• Identity Forge: Identity Forge publicly describes design kits that carry tokens, typography, spacing, layout, motifs, usage guidance, and agent-ready artifacts.