Components API

The sdk.components namespace provides read-only access to the component system — components, variants, variables, instances, and overrides.

Reading components

getAll()

Returns all components in the design.

const components = sdk.components.getAll();
for (const comp of components) {
  console.log(comp.id, comp.name);
}

getById(id)

Returns a single component by ID.

const button = sdk.components.getById('comp-abc');

Variants

getVariants(componentId)

Returns all variants of a component. Each variant represents a viewport-specific version (desktop, tablet, mobile) with a label.

const variants = sdk.components.getVariants('comp-abc');
// [{ id: 'v1', componentId: 'comp-abc', viewport: 'desktop', label: 'default' }, ...]

Variables

getVariables(componentId)

Returns all variables defined on a component. Variables are dynamic properties that can be overridden per instance — any CSS property can be a variable.

const variables = sdk.components.getVariables('comp-abc');
for (const v of variables) {
  console.log(v.name, v.type, v.default);
  // e.g., "Button Text", "textContent", "Click me"
  // e.g., "Background", "backgroundColor", "#3b82f6"
}

Variable data shape:

id — string — Unique identifier
componentId — string — Parent component ID
name — string — Display name
type — string — The CSS property this variable controls (dynamic, any style)
default — any — Default value

Instances

getInstances(componentId)

Returns all placed instances of a component across the design.

const instances = sdk.components.getInstances('comp-abc');
console.log(`Used ${instances.length} times`);
 
for (const inst of instances) {
  console.log(`Page: ${inst.page}, Variant: ${inst.variantId}`);
}

getOverrides(instanceId)

Returns all overrides applied to a specific instance. Overrides are variable values that differ from the component defaults.

const overrides = sdk.components.getOverrides('instance-123');
for (const override of overrides) {
  console.log(override.key, override.value);
}

Statistics

getStats(componentId)

Returns usage statistics for a single component.

const stats = sdk.components.getStats('comp-abc');
if (stats) {
  console.log(`${stats.name}: ${stats.instanceCount} instances across ${stats.usedOnPages.length} pages`);
  console.log(`${stats.variantCount} variants, ${stats.variableCount} variables`);
}

Returns:

id — string — Component ID
name — string — Component name
variantCount — number — Number of variants
variableCount — number — Number of variables
instanceCount — number — Number of placed instances
usedOnPages — string[] — Page IDs where it's used

getDesignStats()

Returns overall design system statistics.

const stats = sdk.components.getDesignStats();
console.log(`${stats.totalComponents} components`);
console.log(`${stats.totalVariants} variants`);
console.log(`${stats.totalInstances} instances`);
console.log(`${stats.totalNodes} nodes across ${stats.totalPages} pages`);

Returns:

totalComponents — number — Total components
totalVariants — number — Total variants
totalVariables — number — Total variables
totalInstances — number — Total instances
totalOverrides — number — Total overrides
totalPages — number — Total pages
totalNodes — number — Total nodes
totalPresets — number — Total presets
componentsByUsage — array — Components sorted by instance count

Example: Design audit

A plugin that reports component usage statistics:

export default definePlugin({
  name: 'Design Audit',
  description: 'Analyze your design system usage',
  controls: {
    showUnused: {
      type: 'toggle',
      label: 'Highlight unused components',
      default: true,
    },
  },
  run(values, sdk) {
    const stats = sdk.components.getDesignStats();
 
    // Find unused components (0 instances)
    const unused = stats.componentsByUsage.filter((c) => c.instanceCount === 0);
    if (unused.length > 0 && values.showUnused) {
      console.log('Unused components:', unused.map((c) => c.name).join(', '));
    }
 
    // Find most used components
    const topUsed = stats.componentsByUsage.slice(0, 5);
    console.log('Most used:', topUsed.map((c) => `${c.name} (${c.instanceCount})`).join(', '));
  },
});