Design System Model

CalibrateDS is built around a unified, tool-agnostic architecture. While Figma is the primary data source today, the system relies on an intermediate model that normalizes design intent into engineering contracts.

The Pipeline

Figma API: The raw, nested JSON representing your design file.
ptb scan: Reads the raw JSON and transforms it into the DesignSystemModel.
Context Engine: Builds rich ComponentContext files for AI and code generation.

Core Types

`DesignSystemModel`

This is the root model saved to .ptb/latest.json after every ptb scan.

interface DesignSystemModel {
  version: string;
  tokens: TokenCollection[];
  components: ComponentDefinition[];
}

`ComponentContext`

This is the richest object in PTB. It is generated during ptb scan and exported to .ptb/context/components/. This context feeds the AI prompt generators and documentation engines.

It contains:

Variant Axes: Explicit properties like size (sm/md/lg) or variant (primary/secondary).
Token Bindings: How fills, strokes, and spacing map to Figma Variables (CSS Variables).
State Contracts: Hover, focus, and active state requirements.
Render Tree: The literal layout and DOM structure expected by the design.
Dependencies: Which other components are required to build this one (direct instances).
Transitive Dependencies: All components reachable by descending into nested instance subtrees — catches hidden dependencies that only appear in non-default variant states.
Slot Contract: Named content slots derived from instance-swap properties and image fill nodes (including asset/image slots for components with background image fills).
Implementation Hints: Correct semantic root element (button, input, select, div, etc.) inferred from the component name and render tree — used to set the correct Props extends interface in generated TypeScript.

[!TIP] The ComponentContext files in .ptb/context/ are designed to be committed to git. They serve as a portable source of truth that can be read by any AI IDE (Cursor, Copilot, Claude Code) without requiring a live Figma connection.

Next Steps

Understand how we track changes to this model over time in the Design Freshness guide.