What is a contract

A contract is the set of necessary behaviors a component needs to serve a guest. How you build them is up to you.

It can also recommend behaviors (SHOULD) and rule some out (MUST NOT).

The contract is defined once, in the SDK catalog. Kismet Elements is one implementation of that catalog, not the definition of it. Your own UI can be another.

What is in a contract

A contract holds only requirements. Each requirement carries a requirement level from RFC 2119. The levels are defined by consequence, not by testability:

Level	Consequence if ignored	Checked by
MUST	Something breaks, or your site ends up with a limited feature set.	The conformance suite; a failure is an error. A MUST is only real if code enforces it: every MUST names a registered check that a runner evaluator implements, and the contract lint fails on a MUST with no check or on a check nobody runs. An unenforceable rule is a SHOULD, not a MUST.
SHOULD	What Kismet recommends as best practice; skip it and the site still works fully. Skipping needs a documented deviation (RFC 2119 §6).	The conformance suite where a check exists; a gap is a warning. Unchecked SHOULDs are marked not yet checked.
MUST NOT	Doing it breaks something.	The conformance suite; a violation is an error. Like a MUST, every MUST NOT names an implemented check, and lint fails otherwise.

Everything the contract does not say is MAY — free space. Layout, markup, animation, framework, and visual design are never in a contract.

Read as a designed object, a contract has three families of requirements, in the vocabulary of Design by Contract (Meyer, 1992):

• the declared props and data the implementation needs up front are the precondition surface;
• the must.* families state what must hold after rendering and interaction — postconditions;
• mustNot entries are invariants: they hold in every state, on every render.

The checks run on the rendered page; there is no runtime assertion machinery.

What is out of a contract

• The look. Brand tokens, CSS, and theme are configuration, not requirements.
• The packaging. Install methods, source files, and emitted events belong to an Element manifest, not to the contract.
• The data types. DTOs and entity shapes are entities — see @kismet-tech/sdk/contracts for types and the glossary for why that entry point is not the contract catalog.

The substitution rule

Any implementation that satisfies a contract’s requirements is substitutable for any other (Liskov & Wing, 1994). That is the swap rule in one sentence: replace a certified page with your own component, or a component with fully custom UI, and whatever you put in its place takes over that contract — the same requirements, the same conformance suite, the same data.

Per-contract documentation shape

Every contract is documented with three tables, in the shape WAI-ARIA §5.2 uses for roles — required, supported, prohibited. For property-card:

Required

Requirement	Level	Check
Show the rental name	MUST	Field bound in DOM
Show a lead image with alt text	MUST	img + alt
Activating the card opens the canonical property URL	MUST	Link href

Supported

Requirement	Level	Check
Show the indicative nightly price when present	SHOULD	Warning only
Use brand slots for color and type	SHOULD	Warning only

Prohibited

Requirement	Level	Check
Show a price as bookable without a dated quote	MUST NOT	Scenario check
Claim the contract without rendering its observable behavior	MUST NOT	Scenario check

The three customization levels

You can adopt Kismet at three depths. The contract stays constant through all three; only the implementation changes.

1. Drop-in page — install a certified Kismet page and configure it. Fastest path; the implementation is Kismet’s.
2. Drop-in components — install certified components (fixtures) into your own pages and swap them one at a time.
3. Fully custom — build your own UI on SDK data, marked with data-kismet-contract, graded by the same suite.

Walking 1 → 3 is the developer applying the strangler fig pattern to their own site: each swap happens behind the contract, which is the seam. Because substitution holds, the guest experience requirements never move.

Where to go next

• The browse channel — the browse-channel and map-view contracts: the results.* actions, one state owner, and the island-sends / receivers-react rule.
• The search island — the search-island contract: the headless useSearchIsland hook, stay settings that live only in the canonical stay URL, the collapsed summary pill, and scope-aware availability.
• The canonical stay URL — the stay-query contract: one stay query format, the StayUrlParam enum, the helpers and hook, and the two gates that make compliance required.
• Contract glossary — every term named after the spec, book, or product it comes from.
• Recipes, contracts, and implementation tests — declare implementations and run the suite.
• ADR 0001 — why the contract is defined in the SDK and why a fourth requirement level was rejected: docs/adr/0001-one-contract-defined-in-the-sdk.md.