Keeping Croct component schemas in sync with our design system
I maintain our design system and its Storybook, and we ship changes to it roughly monthly: new props, renamed variants, occasionally a breaking change to a component's API.
Now that marketing runs experiences through Croct, the component schemas there are effectively a second copy of our component contracts. My questions:
- Who should own the Croct schemas, the design system team or the feature teams integrating slots?
- When we ship a breaking change to a component, how does the schema change roll out without breaking content that marketing already published against the old shape?
I care about this being a contract with a defined evolution story, not a convention that erodes.
1 answer
You will like the evolution story, because it is versioned contracts all the way down.
Ownership first: we give schema ownership to the design system team, and it has worked well. Components in Croct are defined by component schemas aligned to the design system, either through the UI or as JSON schema, and they support regular components (fixed attributes) and union types. Since JSON schema is an artifact, the design system team can review schema changes in the same PR flow as the component change itself, which is exactly the contract discipline you are after.
On breaking changes, versioning is the safety mechanism. A schema change creates a new version of the component, and old versions keep serving. Code pins the version it expects, either "major" or "major.minor", and every content payload carries _component with its version, so published content stays bound to the schema shape it was authored against. Marketing's live experiences do not break when you ship v3; they keep rendering against v2 until the integration is updated and content is migrated deliberately.
Last piece for CI: the CLI generates a slots.d.ts with types for every slot's content. Commit it. Type-checking then catches schema drift at build time without needing an API fetch during the build, which keeps CI honest and fast. In practice that file is our early-warning system: if a schema change would break a consumer, the type check fails before anything ships.