Userface Documentation

v0.1

Documentation for the AI workbench that builds production UI from your design system: contracts, workbench flows, validation, and local engine tooling.

$ npm install @userface/engine

What is Userface

Userface is an AI workbench for building production UI from your design system. It connects your codebase to AI agents so they can discover components, understand contracts, build real interfaces, and validate the result before code lands in the app.

Instead of reviewing hallucinated JSX line by line, you define component contracts (face.json), and Userface keeps generation tied to the real component surface, validation rules, and preview loop your team actually needs.

The workbench is the product surface. The engine, contracts, and MCP tools exist so AI can generate UI from something stricter than vibes and screenshots.

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 validated 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 validated 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