UIF Contracts
UIF (Unified Interface Format) contracts are machine-readable descriptions of your React/Vue/TypeScript components that capture their structure, behavior, and API. LogicStamp extracts these contracts from your codebase to enable semantic change detection, AI context generation, and contract verification.
What is a UIF Contract?
A UIF contract is a structured representation of a component that includes:
Structural footprint
Variables, hooks, components, and functions used
Logic signature
Props, events, and state that define the component's API
Style metadata
Visual and layout information (when --include-style is used)
Semantic hash
Unique identifier based on the component's logic (not implementation details)
File hash
Content-based hash for change detection
Contracts are extracted automatically from your TypeScript/React/Vue files and embedded in LogicStamp bundles.
Contract Structure
Each UIF contract follows the UIFContract schema (version 0.3):
{
"type": "UIFContract",
"schemaVersion": "0.3",
"kind": "react:component",
"description": "Component description from JSDoc",
"version": {
"variables": ["count", "isOpen"],
"hooks": ["useState", "useEffect"],
"components": ["Button", "Card"],
"functions": ["handleClick", "validate"]
},
"logicSignature": {
"props": {
"onClick": {
"type": "function",
"signature": "() => void"
},
"label": {
"type": "string",
"optional": false
}
},
"events": {
"onSubmit": {
"type": "function",
"signature": "(data: FormData) => void"
}
},
"state": {
"isLoading": {
"type": "boolean"
}
}
},
"exports": { "named": ["Button", "ButtonProps"] },
"style": {
"styleSources": {
"tailwind": {
"categories": {
"layout": ["flex", "flex-col", "items-center"],
"spacing": ["py-4", "px-6", "gap-2"],
"colors": ["bg-blue-500", "text-white"],
"typography": ["text-lg", "font-semibold"]
},
"breakpoints": ["md", "lg"],
"classCount": 8
}
},
"layout": {
"type": "flex",
"hasHeroPattern": false
},
"visual": {
"colors": ["bg-blue-500", "text-white"],
"spacing": ["py-4", "px-6"],
"radius": "md"
}
},
"semanticHash": "uif:1a27d0944bbaaf561ee05a01",
"fileHash": "uif:1f0fa0e2c8958d7fc1696036"
}Contract Fields
type
Always "UIFContract" to identify the contract type.
schemaVersion
Schema version string (currently "0.3"). Used for compatibility checking and validation.
kind
Component type identifier:
"react:component"– React functional component"react:hook"– Custom React hook"vue:component"– Vue component (Composition API)"vue:composable"– Vue composable (reusable composition function)"ts:module"– TypeScript module/utility"node:cli"– Node.js CLI script
version
Structural composition of the component:
| Field | Type | Description |
|---|---|---|
variables | string[] | Named variables declared in the component |
hooks | string[] | React hooks used (useState, useEffect, etc.) |
components | string[] | Child components imported and used |
functions | string[] | Named functions defined in the component |
Note: This captures the structural footprint, not implementation details. Adding a new hook or function changes the version.
logicSignature
The public API contract of the component:
props
Object mapping prop names to their type information. Includes type, signature (for function props), and optional flag.
events
Object mapping event names to their signatures. For React components, these are typically callback props that represent events.
state
Object mapping state variable names to their types. Represents the component's internal state structure.
exports(Optional)
Export metadata indicating how the component/module is exported from the file:
"default"– File has a default export"named"– File has a single named export{ named: string[] }– File has multiple named exports (array contains all exported names)
This metadata is used to improve dependency tracking accuracy by distinguishing between internal components (defined in the same file) and external dependencies.
Example:
{"exports": { "named": ["Button", "ButtonProps", "useButton"] }}style(Optional)
Visual and layout metadata extracted when using stamp context style or --include-style.
See Style Metadata Guide for comprehensive documentation.
semanticHash
Unique hash based on the component's logic and contract.
Changes when: Props, events, state, or structural footprint changes.
Does not change for: Comments, whitespace, or implementation details.
fileHash
Content-based hash of the raw file.
Changes when: Any file content modification.
@uif Header Blocks
LogicStamp can extract contracts from JSDoc @uif header blocks in your source files. This allows you to provide explicit contract information or override automatic extraction.
Basic Format
/**
* @uif Contract
* @description Button component for user interactions
* @kind react:component
*/
export function Button({ onClick, label }: ButtonProps) {
// ...
}When generating context with --include-code header, LogicStamp includes the @uif header block in the bundle.
What Changes a Contract?
Changes semanticHash
- Adding/removing/renaming props
- Changing prop types
- Adding/removing events
- Changing state structure
- Adding/removing hooks
- Adding/removing child components
- Adding/removing named functions
Does Not Change semanticHash
- Comments
- Whitespace/formatting
- Variable names (unless part of public API)
- Internal logic refactors
- Implementation details
Note: fileHash always changes for any file content modification, including cosmetic changes.
Best Practices
Keep contracts stable – Avoid unnecessary changes to props, events, or state structure
Use semantic hashes – Rely on semanticHash to detect meaningful changes, not fileHash
Document with @uif – Use @uif header blocks for explicit contract documentation
Validate regularly – Run stamp context validate to catch schema drift
Compare before commits – Use stamp context compare to review contract changes