@super-ic/interaction-contracts

The schema layer of the SuperIC design system. Zod schemas and a small vocabulary tokenizer that together decide whether a design-system contract, an accepted manifest, or a generated registry snapshot is well formed.

This package holds no React, no CSS and no components. It is the thing that says no when a contract is written wrong.

Install

npm install @super-ic/interaction-contracts zod

zod (^3.24.2) is a peer dependency, deliberately. Schemas from this package are composed into consumer schemas and their inferred types cross the boundary, so both sides must resolve the same zod instance. If zod were bundled as a direct dependency, a consumer on a different minor could end up with two copies and instanceof checks and z.infer types would silently stop lining up.

Exports

Everything is exported from the package root.

The generated component registry and agent guides are also public package data:

| Import | What it is | | --- | --- | | @super-ic/interaction-contracts/registry.json | The generated component registry as JSON. | | @super-ic/interaction-contracts/guides/<component-id>.md | The generated agent guide for one component, pattern or recipe. |

Both public data trees come from the same compiler result as design-system/generated/component-contracts. contracts:check compares every expected byte and rejects missing, stale or hand-added packaged files.

Interaction contracts

| Export | What it is | | --- | --- | | InteractionContractSchema | The full contract for one component, pattern or layout. | | InteractionContract | z.infer of the above. | | tokenizeImplementationVocabulary | Finds implementation vocabulary inside prose. | | ImplementationVocabularyKind, ImplementationVocabularyToken | The tokenizer's result types. |

InteractionContractSchema requires schemaVersion: 1, a semver contractVersion, and an id matching ^(component|pattern|layout)\.[a-z0-9.-]+$. anatomy, publicApi, variants, useCases, nonUseCases, limits and states must each hold at least one entry. A contract that declares no limits and no non-use-cases is rejected rather than accepted as unconstrained. Objects are .strict(), so an unexpected key fails instead of being dropped.

The schema enforces platform neutrality itself. After the shape check, InteractionContractSchema walks every string leaf in the parsed contract and rejects it if any leaf names implementation detail. A contract whose state meaning says "set display: grid" or "add bg-blue-500" fails to parse. This is the single most surprising behaviour in the package: a structurally perfect contract can still be rejected on its prose.

tokenizeImplementationVocabulary is the function behind that check, exported so consumers can run the same rule over prose that is not itself a contract. It recognises eleven kinds: color-literal, css-custom-property, css-declaration, css-function, css-keyframes, css-state-selector, css-unit, framework-api, implementation-term, platform-member and utility-class. It normalises comments before matching, so display/* one */:/* two */grid is still found as a CSS declaration, so you cannot smuggle a declaration past it with comment noise. Results are de-duplicated on kind plus lexeme.

Current component authority

Use @super-ic/interaction-contracts/registry.json and its generated guides for the current 106 component/recipe contracts. The source is design-system/component-contracts/components.json; each accepted record is tied to root review and executed source-bound receipts. The schemas below remain supported compatibility APIs. The historical family index is intentionally empty and is not the current component acceptance authority.

The historical twenty template references stay classified legacy. Current product composition comes from TEMPLATE_ROUTE_COMPOSITIONS in @super-ic/app-patterns, resolving each component ID against this generated canonical registry.

Registry and accepted manifests

| Export | What it is | | --- | --- | | RegistryItemSchema, RegistryItem | One entry in the accepted registry. | | ContractStatusSchema | reference, candidate, accepted, adapt, compatibility, product-only, retire, exception. | | AcceptedEvidenceSchema | The evidence an accepted item must cite. | | PlatformApplicabilitySchema, TokenExtensionSchema | Platform and token-extension shapes. | | CompatibilityLifecycleEvidenceSchema, RetireLifecycleEvidenceSchema, ExceptionLifecycleEvidenceSchema | Per-lifecycle evidence. | | AcceptedManifestSchema, AcceptedManifest | One family's manifest file. | | AcceptedFamilySchema | tokens, brands, icons, components, patterns, layouts. | | flattenAcceptedManifests | Merges manifests into one bytewise-sorted, duplicate-free item list. | | GeneratedRegistrySnapshotSchema, GeneratedRegistrySnapshot | The generated snapshot, including its sourceHash. |

AcceptedManifestSchema pins schemaVersion: "1.0.0" and contractVersion: "0.1.0" as literals and additionally cross-checks family against kind: a pattern item cannot appear in the components manifest, and a duplicate id inside one manifest is an error.

flattenAcceptedManifests sorts by id using a byte comparison, not a locale comparison, so the output is stable across machines and locales.

Source classification

| Export | What it is | | --- | --- | | SOURCE_CLASSIFICATIONS | The 15 classifications, unique and bytewise sorted. | | SourceClassificationSchema | z.enum over the above. | | SourceClassification | The inferred union type. |

SOURCE_CLASSIFICATIONS is generated from the classification contract, not hand-written. The generated module it comes from is internal: it is not reachable through the exports map, so import SOURCE_CLASSIFICATIONS from the package root and nothing deeper.

Bootstrap

interactionContractsBootstrap reports { packageName, contractVersion } for consumers that want to assert which contract line they are compiled against.

Usage

import {
  InteractionContractSchema,
  SourceClassificationSchema,
  tokenizeImplementationVocabulary,
} from "@super-ic/interaction-contracts";

// Throws on a malformed shape *and* on prose that names implementation detail.
const contract = InteractionContractSchema.parse(JSON.parse(raw));

// Run the same neutrality rule over prose that is not a contract.
const leaks = tokenizeImplementationVocabulary(releaseNote);
if (leaks.length > 0) {
  throw new Error(`copy names implementation detail: ${leaks[0]!.kind} ${leaks[0]!.lexeme}`);
}

const classification = SourceClassificationSchema.parse("pattern");

Authoring inputs

The pattern contract JSON files that live beside this package's source remain authoring inputs and are not published. Consumers can read the compiled registry and guides from the public package exports without access to the design-system repository.

prepack verifies that the checked-in generated output still matches a fresh generation before it builds, so a stale generated module cannot be packed.