Face UI

React component library and design system used in Userface App.

Face UI contains 45 components for controls, forms, navigation, overlays, data display, feedback, and layout. The package includes typed APIs, CSS tokens, light and dark themes, interaction states, and documented compatibility rules.

Each component also has a JSON contract. Userface uses these contracts to render useful states, build property controls, validate props, and give the AI agent exact information about the available component API.

Status: Working library, active development

System role

Face UI started as the interface foundation for Userface App. The same components then had to work in application code, isolated previews, property controls, documentation, and AI-generated interfaces without acquiring a different definition in every tool.

1.1

One component model across code and tools

Every public component combines a React implementation, typed props, CSS styles, supported states, a JSON contract, and a status in the component registry.

The same definition drives the product interface, isolated playground, property panel, documentation, and agent context. A new variant or renamed prop therefore becomes visible across all of these surfaces.

This keeps the rendered component and the information available to developers and AI tools aligned with the source code.

1.2

45 components with clear support status

The public surface covers controls, forms, overlays, navigation, data display, feedback, and layout. Button, Input, Select, Table, Modal, Tabs, Tree, Command, Toast, Upload, and Carousel follow the same typography, spacing, membrane, focus, and state rules.

The registry currently contains 33 stable components, 10 beta components, and 2 deprecated compatibility aliases. Stable components require a migration path for breaking changes; beta APIs may still change; deprecated names remain available only for existing imports.

The status is consumed by documentation and tooling, so compatibility is visible before a component is selected or generated into an interface.

Fig. 1.Contracts turn component props and saved states into controls that can be changed and rendered live.

Component architecture

Typed React APIs define how a component is used in code. Face contracts expose the same props, options, states, and rules as structured data for preview, validation, and AI tooling.

2.1

Props describe behavior, not only appearance

Component APIs represent product intent as named props and states. Loading, destructive action, controlled selection, expanded navigation, open overlays, and responsive presentation are handled by the component instead of local CSS and screen-specific logic.

JSON contracts live next to the source and record prop types, options, defaults, reproducible examples, usage guidance, alternatives, and, where relevant, anatomy, keyboard behavior, and accessibility notes.

A generated registry and runtime entry expose this information to Userface Engine, the playground, and other tools without parsing documentation written for people.

2.2

Interaction stays inside the component

Interactive components own their opening, selection, focus, dismissal, keyboard, loading, disabled, and responsive states. Repeated behavior is implemented once and travels with the component into every screen.

Contracts record expected semantics and keyboard behavior, interaction tests cover critical state changes, and the registry keeps accessibility and mobile review status visible per component.

Incomplete work remains explicit: beta status and review metadata show where an API or behavior can still change instead of presenting every component as equally finished.

Design system

3.1

One token source generates every delivery format

Canonical JSONC files define colors, semantic surfaces and actions, typography, spacing, shape, effects, and themes. Build scripts generate CSS files, a token manifest, theme outputs, and preview metadata from these sources.

Semantic --uf-* variables control color, control geometry, spacing, typography, motion, borders, radii, and shadows. Light and dark themes use data-theme and token overrides rather than separate component styles.

Face UI ships plain CSS scoped through data-scope and data-part attributes. Applications can use the library without Tailwind, a CSS-in-JS runtime, or a React provider.

3.2

The repository builds an installable package

The build produces ESM, CommonJS, TypeScript declarations, CSS, JSON contracts, component metadata, runtime entries, and documented subpath exports. Consumers import the main package or a canonical component path without depending on the repository structure.

Deprecated aliases are isolated in a compatibility entry and point to canonical replacements. Existing imports continue to work while new code sees only the current API.

The release check verifies generated tokens, contracts, gallery data, package builds, interaction tests, export smoke tests, and the final npm archive.

3.3

Face UI supplies exact context to Userface

Userface App uses Face UI for its own interface. Userface Engine reads the same package registry and contracts to discover components, build prop controls, load saved states, validate props, and prepare context for the agent.

The playground provides a direct check of this connection. Missing defaults, invalid state presets, unsupported props, and rendering errors become visible when the component is opened rather than after it is used in a generated screen.

Face UI therefore serves as both a product library and a working test of whether a design system contains enough structured information for another tool to use it correctly.

The visual language is compact and neutral. It is intended for product tools used for long sessions, where hierarchy, state, and available actions must remain clear without decorative framing.

Current state

4.1

A library used by product and tooling

45 registered components used in the Userface App interface.
Typed React exports, plain CSS, semantic tokens, and light and dark themes.
Per-component JSON contracts, reproducible states, a generated registry, and a runtime entry for Userface Engine.
Automated checks for tokens, contracts, gallery data, builds, tests, exports, and the npm package.