Internals

CalibrateDS (ptb) operates as a pipeline. It extracts data, normalizes it, and passes it to generators.

Pipeline Architecture

1. Figma API: The raw data source.
2. Scanner & Normalizer: The packages/core logic that reads the raw JSON and creates the DesignSystemModel.
3. Diff & Plan: Compares the snapshot against the previous version to identify affected components and determine the dependency order.
4. Generator Registry: Dispatches the model to a framework-specific generator plugin (like React).

Generator Plugins

Generators are framework plugins registered at CLI startup.

Every generator implements IGenerator:

interface IGenerator {
  writeComponents(model, config, options?): Promise<WriteComponentsReport>;
  writeTokens(model, config, options?): Promise<WriteTokensReport>;
  writeScaffold(args: ScaffoldArgs): Promise<ScaffoldWriteReport>;
  pruneComponents(config, staleEntries): Promise<PruneResult>;
}

The current implementation is ptbReactGenerator. To add support for Vue or Svelte, a new package implementing IGenerator would be registered.

Naming Strategy

Component names in Figma are display names (e.g. "Notification Item"). The normalizer converts them to canonical identifiers using a single shared strategy:

• toCanonicalComponentName("Notification Item") → "NotificationItem" (PascalCase, icon-aware)
• toCanonicalFolderSlug("Notification Item") → "notification-item" (kebab-case, icon-aware)

Icon components are detected by name pattern and normalized separately so they receive SVGAttributes<SVGSVGElement> rather than generic HTML attributes.

Inline Metadata Headers

Every file written by PTB includes a PTB_METADATA comment header. This is how PTB detects user-modified files to avoid accidentally overwriting manual code.

// PTB_METADATA {"componentId":"...","contextHash":"abc123","generatedAt":"...","framework":"react"}

If you remove this header, PTB assumes you want to take over ownership of the file and will never overwrite it without the --force flag.

Custom Code Regions

Within PTB-generated files, you can protect blocks of hand-written code from being overwritten on regeneration:

// @ptb-custom-start
// Your hand-written code here — preserved on re-generate
// @ptb-custom-end

PTB extracts these sections before regenerating and injects them back in the same position.

Verify Verdict

ptb verify computes a composite score from three independent signals:

1. Token score (primary): fraction of Figma design text tokens found in the rendered DOM
2. Structure score: fraction of expected slot types (text, image) present in the DOM
3. Pixel score: full-frame pixel diff similarity (0.0–1.0)

The verdict uses whichever signals are available, in that priority order. Pass threshold: 0.90. Warn threshold: 0.70. This means a component with correct text content and DOM structure can pass verification even when pixel alignment varies slightly due to font rendering.

Next Steps

Learn how to enforce design drift in CI in the CI Integration guide.