Userface Documentation

v0.1

AI-native UI infrastructure. Connect your components, let agents build interfaces, validate with contracts.

$ npm install @userface/engine

What is Userface

Userface is AI-native UI infrastructure. It connects your codebase to AI agents so they can discover your components, understand their contracts, build real interfaces, and validate every screen against quality rules — automatically.

Instead of writing boilerplate UI by hand or reviewing AI-generated code line by line, you define component contracts (face.json), and the engine ensures that every generated interface is correct, accessible, and consistent with your design system.

Think of it as TypeScript for UI — but the type-checker runs at generation time, not compile time. AI agents write the code; Userface makes sure it's good.

Why Userface

Without Userface

With Userface

AI agents hallucinate components that don't exist in your library

Agents query the registry and only use real components with valid props

Generated UI uses wrong prop types, missing required fields

face.json contracts are validated automatically — violations caught instantly

No way to enforce design system rules on AI-generated code

Policy packs check accessibility, naming, composition rules on every file

Manual review of every AI-generated screen

Automated validation in CI — merge only if score passes threshold

Installation

Install

npm install @userface/engine

The engine ships as a single npm package with zero required runtime dependencies. React and esbuild are optional peer dependencies — required only if you use SSR rendering or the built-in bundler.

Optional peers

# Peer dependencies (optional)
npm install react react-dom   # for SSR rendering
npm install esbuild           # for local bundling

Quick Start

Three steps to go from zero to a governed UI workflow:

Connect your project

Step 1

npx userface connect

Scans your codebase, detects components, and generates face.json contracts for each one.

Agent builds UI

Step 2

// In your AI agent (Cursor, Claude, etc.)
// The MCP server exposes tools:
component_list({ dir: "./src/components" })
component_analyze({ path: "./src/components/Button" })
ui_materialize({ doc: myUiDoc, mode: "code" })

AI agents use MCP tools to discover components, understand their props, and generate framework-specific code from declarative UI descriptions.

Validate

Step 3

npx userface validate ./src/pages/Dashboard.tsx

Validates the generated UI against your component contracts, design system rules, and accessibility requirements. Returns violations, scores, and fix hints.

First Governed Build

Here's a complete example: creating a settings panel from a ui@1 document, then validating the output.

docs/examples/settings.ui@1.json

{
  "version": "ui@1",
  "root": {
    "type": "Panel",
    "props": { "title": "Settings" },
    "children": [
      {
        "type": "Input",
        "props": {
          "label": "Name",
          "value": { "$ref": "user.name" }
        }
      },
      {
        "type": "Button",
        "props": {
          "text": "Save",
          "onClick": { "$action": "form.submit" }
        }
      }
    ]
  }
}

Build & validate

# Materialize to React code
npx userface materialize ./docs/examples/settings.ui@1.json --output ./src/pages/Settings.tsx

# Validate the result
npx userface validate ./src/pages/Settings.tsx
# ✓ All props match contracts
# ✓ Accessibility: labels present
# ✓ 0 violations