# Keeping Croct component schemas in sync with our design system

Asked by Dominic Faber on 2026-01-27. Tags: workflow, components, design-system, versioning.

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:

1. Who should own the Croct schemas, the design system team or the feature
   teams integrating slots?
2. 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

### Accepted answer from Aoife Nolan (2026-01-27)

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.